Configuring BMC Helix Client Gateway
Related topics
Use the BMC Helix Client Gateway setup tool (KWIC installer) to install the client gateway as a service. After you set up the gateway service, use the information in this topic to configure it as per your requirements.
Refer to the following topics for more information about BMC Helix Client Gateway.
- Requirements - System requirements and Gateway configuration options
- Installing - Downloading the installation files and installing the BMC Helix Client Gateway for the first time
- Upgrading - Upgrading from an older version of the BMC Helix Client Gateway to the latest version
To check the gateway service version
You can check the version number of BMC Helix Client Gateway using one of these methods:
- Check the console output used to start the gateway service and look for the line that shows the version.
For example, INFO Kaazing KWIC (<version>). - Locate the version number in the log file at <KWIC_INSTALL_DIR>/log/kwic.log.
If the client gateway runs as a service, this log is the only source of version information.
To configure the gateway service to run at system startup
As a system administrator, to configure BMC Helix Client Gateway to run at system startup, do the following:
- Perform one of the following steps based on your operating system:
- Linux/Mac: From the command line, run the setup tool, sudo kwic.setup, located in KWIC_HOME.
- Windows: Right-click cmd and choose Run as Administrator, then run kwic.setup.
- Enter your system administrator password.
- Select Configure KWIC to run at system startup (c), and then press Enter.
The setup tool indicates whether the client gateway service is running.
To stop a BMC Helix Client Gateway instance
You might need to restart a BMC Helix Client Gateway instance if you need to change its configuration file. For example, <KWIC_INSTALL_DIR>/conf/kwic-config.xml.
To stop a BMC Helix Client Gateway instance on Windows:
- Use the Windows Services Manager.
- Press Ctrl+C at the command prompt that was used to start BMC Helix Client Gateway or close the command prompt.
- Use the net stop command to stop the BMC Helix Client Gateway service.
To stop a BMC Helix Client Gateway instance on Linux, UNIX, and Mac:
- Kill the process at the command line.
- Use the Linux or Ubuntu (Upstart) service stop command.
To restart a BMC Helix Client Gateway instance
To restart a BMC Helix Client Gateway instance, perform one of the following from the bin directory in your installation directory:
- Linux/Mac: run the sudo ./kwic.start command
- Windows: run kwic.start.exe as administrator
BMC Helix Client Gateway configuration elements
This section describes the main BMC Helix Client Gateway configuration elements for cloud clients connecting to on-premises servers and on-premises clients connecting to cloud servers.
| Element | BMC Helix Client Gateway Cloud | BMC Helix Client Gateway On-Premises |
| proxy | Proxies connect to the cloud client or cloud server. Once the connection is established, BMC Helix Client Gateway acts as a proxy for a client or server that cannot natively establish TCP or HTTP connections over the Web. | Proxies connect to the on-premises server or client. For inbound connections, the BMC Helix Client Gateway On-Premises instance proxies connections using WebSocket and a reverse proxy (SOCKS). For outbound connections, the BMC Helix Client Gateway On-Premises instance uses WebSocket to proxy connections over the web. |
| accept | The URL on which the proxy service accepts connections. A tcp:// scheme is used to accept a connection from a client. In a forward connection, a WebSocket (ws://) scheme is used to accept a connection from the On-Premises instance. | In a reverse connection, a pipe:// scheme is used, and the On-Premises instance accepts connections from the BMC Helix Client Gateway hub at the URL in accept. The pipe:// scheme is a URI scheme internal to BMC Helix Client Gateway and used to create a named, logical channel between the Cloud and On-Premises instances. With BMC Helix Client Gateway, one end of the pipe is in the BMC Helix Client Gateway Cloud, and the other is in the BMC Helix Client Gateway On-Premises. The pipe.transport element is where the transport is set to SOCKet Secure (SOCKS) over WebSocket. Example: |
| connect | The URL of a service to which the proxy service connects. In a reverse connection, a pipe:// scheme is used, and the Cloud instance connects to the On-Premises instance at this URL. In a forward connection, a tcp:// scheme is typically used, and the Cloud instance connects to the cloud server at this URL. | In a reverse connection, a tcp:// scheme is typically used, and the On-Premises instance connects to an on-premises server at this URL. In a forward connection, a WebSocket scheme is used to connect to the Cloud instance. |
| accept-options | In a forward connection, the Cloud instance proxy service uses accept-options to apply the ws.inactivity.timeout setting. Setting accept-options on the proxy service element only affects that service and overrides any defaults. | In a reverse connection, the On-Premises proxy service uses this element to add SOCKS-related settings, such as pipe.transport, socks.mode, and socks.transport. |
| connect-options | In a reverse connection, the Cloud proxy uses this element to add SOCKS-related settings, such as pipe.transport, socks.mode, and socks.transport. Setting connect-options on the proxy service element only affects that service and overrides any defaults. | In a forward connection, the On-Premises proxy service uses connect-options to apply the ws.inactivity.timeout setting. |
| pipe.transport | In a reverse connection, pipe.transport specifies a URI to use as the transport layer in the pipe between the Cloud and On-Premises instances. This setting is not used in a forward connection. | In a reverse connection, this setting is identical between the Cloud and On-Premises proxy services. |
| socks.mode | Initiates a connection using the SOCKet Secure (SOCKS) protocol. The value of reverse initiates the connection from the On-Premises instance to the Cloud instance. The connection initiates outwards from behind the on-premises firewall. This setting is not used in a forward connection. | In a reverse connection, this setting is identical between the Cloud and On-Premises proxy services.
|
| socks.transport | Specifies a URI for use as a transport layer under the SOCKS transport. This setting is not used in a forward connection. | In a reverse connection, this setting is identical between the Cloud and On-Premises proxy services. |
| ws.inactivity.timeout | Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval). The Cloud and On-Premises instances drop the connection if they cannot communicate with each other within the specified time limit. You can specify your preferred time interval in milliseconds, seconds, minutes, or hours. For example, valid values include: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit, seconds will be used as the default. | In a reverse connection, this setting is identical between the Cloud and On-Premises proxy services. |
| socks.ssl.verify-client | For reverse connections, socks.ssl.verify-client on a connect specifies that the Cloud instance requires that the On-Premises instance provide a client digital certificate that the Cloud instance can use to verify the On-Premises instance's identity. | This element is not used by the On-Premises instance. |
| ssl.verify-client | For a forward connection, ssl.verify-client on an accept specifies that the Cloud instance requires that the On-Premises instance provide a client digital certificate that the Cloud instance can use to verify the On-Premises instance's identity. | This element is not used by the On-Premises instance. |
| property | You can use this element to specify default values for configuration elements. Configuring property defaults is optional but recommended because it allows you to define property values once and have the value propagated throughout the configuration when the BMC Helix Client Gateway instance starts. You can replace any value in the configuration file with a property using the dollar-sign and curly brace format (such as ${service.hostname}). Example: | This element is used the same on all BMC Helix Client Gateway instance types. |
BMC Helix Client Gateway proxy service configuration examples
The following configuration shows the proxy services for both the BMC Helix Client Gateway Cloud and On-Premises instances side by side, showing how their settings relate to each other.
Cloud client to on-premises server (reverse connection)
In a reverse connection configuration, the pipe:// connection shows how the BMC Helix Client Gateway instances are connected, and the identical connect-options and accept-options show the pipe transport layer.
On-premises client to cloud server (forward connection)
In a forward connection configuration, the ws:// connection shows how the BMC Helix Client Gateway instances are connected, and ws.inactivity.timeout specifies the maximum number of seconds that the BMC Helix Client Gateway connection can be inactive.
(Windows) To add a proxy to the BMC Helix Client Gateway configuration
- Open File Explorer, right-click This PC, and then select Properties.
- Select Advanced system settings.
- On the Advanced tab, select Environment Variables.
- Under System variables, select New.
The New System Variable dialog box appears. - In the Variable name box, enter GATEWAY_OPTS.
- In the Variable value box, enter -Xmx1024m -Dhttp.proxyHost=<Hostname> -Dhttp.proxyPort=<Port>.
Example: -Xmx1024m -Dhttp.proxyHost=10.10.10.10 -Dhttp.proxyPort=8080
Where:- proxyHost is the hostname or IP address
- proxyPort is the port number
- Select OK to apply the settings.
- Restart the BMC Helix Client Gateway (Kaazing) service.
(Linux) To add a proxy to the BMC Helix Client Gateway configuration
- Open the kwic.start file from the bin directory in a text editor.
- (Optional) Locate the process ID by running:
ps -ef | grep kaazing - Add the proxy setting after the line # The following line is used by KWIC. Do not remove.:
GATEWAY_OPTS="$GATEWAY_OPTS -DGATEWAY_CONFIG=$GW_HOME/conf/kwic-config.xml -Dcom.kaazing.kwic.logging=on -Xmx1024m -Dhttp.proxyHost=10.10.10.10 -Dhttp.proxyPort=8080" - Save the file.
- Restart the BMC Helix Client Gateway (Kaazing) service.
To bypass the proxy for on-premises TCP connections
To bypass the proxy for an on-premises TCP connection, enter the proxy setting value as shown in these examples
-Xmx1024m -Dhttps.proxyHost=10.10.10.10 -Dhttps.proxyPort=8080 -Dhttps.nonProxyHosts=10.*|10.10.20.10
Proxy limitations
- Proxies with authentication aren't supported by the gateway.
- Use of a wildcard, for example, *.foo.com, isn't supported by the gateway. Use IP addresses instead.
- The gateway supports only point-to-point connectivity. Any integrations with redirects aren't supported.
Proxy connection issue in earlier versions
In versions earlier than 6.0.2 of BMC Helix Client Gateway, a proxy rejects a connection when the gateway initiates a Secure WebSockets (wss://) connection over HTTPS (https://) through an intermediate proxy. This issue occurs because the HTTP CONNECT request lacks a Host header.
Workaround for earlier versions: Establish a direct connection between the on-premises gateway and SaaS endpoints by bypassing the intermediate proxy server.
In BMC Helix Client Gateway version 6.0.2 and later, the Host header is included in the HTTP CONNECT request, and the connection is established successfully.