Using Kaazing WebSocket Intercloud Connect (KWIC) 5

Want to jump right in? Run the KWIC setup tool now.

Need to test your deployment? See Verifying KWIC Deployment and KWIC 5 Logging and Troubleshooting.

Kaazing WebSocket Intercloud Connect (KWIC) provides highly secure, hybrid cloud connectivity. KWIC enables rapid delivery of new applications and services in the cloud while securely connecting to your existing infrastructure with no hardware or VPN required.

KWIC leverages modern web standards such as WebSocket, HTTP and TLS (SSL) encryption to extend your TCP-based protocols site-to-site. It allows you to connect your TCP and HTTP enterprise services natively, securely and on-demand. KWIC extends infrastructure-to-infrastructure connectivity further by providing additional enterprise features, such as secure end-to-end connections, authentication interfaces and DMZ-friendly installation.

Here is an example of the basic KWIC deployment topology, where a route, route A, is established between a cloud-based client and an on-prem server across the established KWIC connection. The client-to-server connection moves in the typical cloud-to-on-prem direction and the KWIC connection is established in the opposite direction. Because the KWIC connection goes from the on-prem to the cloud, no inbound firewall ports are opened:

Figure: Simple KWIC Topology

Table of Contents

This document covers the following information:

Minimum System Requirements

For the latest information, see the KWIC Release Notes.

KWIC 5 supports the following operating systems, or higher:

Note: KWIC 5 includes an embedded Java Runtime Environment (JRE). KWIC 5 uses Java Runtime Environment (JRE) Java 8 (version 1.8.0_77) or higher.

The KWIC 5 distribution is a tar.gz file for Linux and Mac systems and a zip file for Windows. Both files contain a setup tool that walks you through the steps of configuring KWIC.

Checking the KWIC Version

Once you have KWIC up and running you might need to check its version number for compatibility reasons. You can check the KWIC version in the following ways:

KWIC 5 Topology and Terms

Let's take a look at a more complicated KWIC 5 topology:

Figure: Advanced KWIC 5 Topology

In this topology, a KWIC connection is established by the KWIC On-Prem instance connecting to the KWIC Cloud instance.

KWIC Components and Tools

Before you get started with KWIC 5, review the components and tools used to configure KWIC 5, described in the following table:

Component Description
KWIC Cloud A KWIC server that manages cloud client and server connections. Cloud client connections pass through the KWIC Cloud to the KWIC On-Prem and onto the on-prem server. On-prem client connections pass through the KWIC On-Prem to the KWIC Cloud and onto the cloud server.
KWIC On-Prem A KWIC server that connects and protects on-prem resources. The KWIC On-Prem manages KWIC connections to and from the KWIC Cloud.
Endpoints The endpoints in a KWIC deployment are clients and servers that use KWIC for communication.
Route A route is any path over the KWIC deployment, in either direction. The route can be from a cloud client through the KWIC Cloud to the KWIC On-Prem and onto the on-prem server, or it can be from an on-prem client through the KWIC On-Prem to the KWIC Cloud and onto the cloud server.
Cluster A KWIC cluster is a group of KWIC Cloud servers that use the KWIC clustering service.

How Does KWIC Work?

Traditionally, web architectures require that you open inbound ports to allow connectivity to internal systems and services in your trusted network. A typical configuration must open ports to allow TCP, HTTP, or WebSocket connectivity through a firewall. For most administrators, opening an inbound port for the outside world is a necessary but undesirable solution because it instantly increases vulnerability to outside hacks and attacks. Companies are reluctant to open up ports in firewalls because each open port is another potential attack vector. KWIC protects your trusted network by initiating the connection from the on-prem, trusted network towards the cloud. Using KWIC, you can close all of your inbound ports while still allowing clients to initiate connections.

To implement KWIC, you configure a KWIC server in the cloud, which receives a reverse connection (Socket Secure (SOCKS) connection) from the KWIC On-Prem server in the trusted network. With this architecture, a client can talk to the back-end service or message broker through a firewall. Another benefit of KWIC is that your current architecture remains valid, without requiring changes. For example, neither the client nor the back-end service or message broker are aware of the reverse connection because it is completely transparent to the rest of the architecture.

Learn about KWIC 5 with KWIC Docker Tutorials

KWIC 5 includes several KWIC tutorials to get you up and running quickly. The tutorials use Docker and Docker Compose to demonstrate KWIC. The tutorials are designed to be done in order, starting with a simple KWIC deployment and then adding security and complexity to the topology.

The tutorials are available on Github and cover the following scenarios:

  1. Simple - This is the introductory KWIC deployment scenario, with cloud nodes connecting to on-prem nodes behind a firewall. There is no actual firewall deployed in the tutorial, but the configuration is consistent with a firewall being present. All endpoint servers are stubbed out with echo services for simplicity.
  2. TLS Security Enforced - TLS is used to keep data private, but is also used to establish machine-to-machine trust between the cloud and on-prem KWIC instances. The cloud instance presents a server certificate to the on-prem instance, and the on-prem instance presents a client certificate to the cloud instance for mutual authentication. Clients and servers then communicate over KWIC and their data is encrypted as it passes over the KWIC segment of the route.
  3. Multi-tenant Deployment - This tutorial shows how to have a single KWIC Cloud instance servicing multiple independent On-Prem tenants.
  4. High Availability - In this tutorial, the cloud has two KWIC instances and the on-prem has two KWIC instances. If any single instance fails on either or both sides, there is still a path for clients to connect.

KWIC 5 Setup Walkthroughs

The KWIC setup tool (KWIC_HOME/kwic.setup) is a simple method for setting up KWIC Cloud and KWIC On-Prem instances. This section describes how to set up the two most common KWIC deployment scenarios.

Note: Whenever changes are made using kwic.setup, those changes are written to the KWIC configuration file immediately, and not simply when you exit the tool.

For both scenarios, you can any two computers. We will use one machine for the KWIC Cloud instance and one machine for the KWIC On-Prem instance. We use the same computers to simulate cloud and on-prem clients and servers.

Notes:

Walkthrough 1 - Cloud Clients Connecting to On-Prem Servers

There are two steps in setting up a KWIC deployment:

  1. Connect the KWIC On-Prem instance and the KWIC Cloud instance. This is established with an outbound connection from the KWIC On-Prem instance to the KWIC Cloud instance. The KWIC connection setup can be summarized like this:

    client | KWIC Cloud <- web <- KWIC On-Prem | server

    The | symbol is used to indicate that the cloud client and on-prem server have not yet communicated over the KWIC connection.

  2. Connect the cloud client to the on-prem server over the KWIC connection. The client-server connection can be summarized like this:

    client -> KWIC Cloud -> web -> KWIC On-Prem -> server

Walkthrough 1 - Setup Overview

This walkthrough has the following sections and steps to perform:

  1. Set Up KWIC Cloud Instance.
    1. Download KWIC.
    2. Enter the IP address and port the KWIC Cloud instance will use to listen for the KWIC On-Prem instance
    3. Enter a KWIC proxy service name. The KWIC Cloud proxy service will proxy cloud client communications to the KWIC On-Prem instance.
    4. Enter a port number for the KWIC Cloud instance to use when listening for client communications.
    5. Start the KWIC Cloud instance.
  2. Set Up KWIC On-Prem Instance.
    1. Download KWIC.
    2. Enter the same KWIC proxy service name you used when configuring the KWIC Cloud proxy.
    3. Enter the IP address and port number of the on-prem server for the KWIC On-Prem instance to connect with. The KWIC On-Prem proxy service will proxy on-prem server communications to the KWIC Cloud instance.
    4. Enter the hostname or IP address, and port number, of the KWIC Cloud instance. This enables the KWIC On-Prem instance to initiate the outbound connection to the KWIC Cloud instance and establish the KWIC connection.
    5. Start the KWIC On-Prem instance.
  3. Walkthrough 1 - Verifying KWIC Deployment.
    1. Simulate an on-prem server on the same server running the KWIC On-Prem instance.
    2. Simulate a client on the same server running the KWIC Cloud instance.
    3. Send a message from the client to the server, and verify that it arrived.

Here is a short video showing the configuration steps for this walkthrough:

Walkthrough 1 - Set Up KWIC Cloud Instance

To configure the KWIC Cloud instance, do the following:

  1. Log into the machine you are using for the KWIC Cloud server. Ensure the system meets the system requirements.
  2. Download the KWIC distribution package from https://kaazing.com/download/#kwic.
  3. Unpack the compressed download of KWIC to any directory location and then rename it as necessary (for example, you could rename it to C:\kwic, C:\kwic-cloud or /home/username/kwic-cloud). The top-level directory for KWIC is represented in this document as KWIC_HOME because the actual directory destination depends on your operating system.
  4. From the command-line, run the KWIC setup tool, kwic.setup (kwic.setup.exe on Windows), located in KWIC_HOME. Here is the welcome screen:
    Figure: kwic.setup Welcome Screen

    You will now configure the KWIC Cloud instance. This involves configuring the KWIC Cloud instance to listen for connections from the KWIC On-Prem instance and the cloud client, as shown in the bolded section of this topology:

    client -> KWIC Cloud <- web <- KWIC On-Prem -> server

  5. On the first screen of KWIC setup tool, choose Set up a Cloud instance by typing c, and then press Enter. The KWIC Cloud Instance setup screen appears:
    Figure: Cloud Instance option

    In this screen you will select the IP address and port number that the KWIC Cloud instance will use to listen for a connection from the KWIC On-Prem instance.

    Why am I doing this? Later in this walkthrough you will set up and start the KWIC On-Prem instance. When the KWIC On-Prem instance starts, it contacts the KWIC Cloud instance to establish the KWIC connection. The connection attempt looks like this:

    KWIC Cloud <-- web <-- KWIC On-Prem

    The KWIC On-Prem instance contacts the KWIC Cloud instance using a specific IP address and port number, and so you need to configure the KWIC Cloud instance to listen on that IP address and port number.

  6. From the list of available IP addresses, enter the number next to the IP address that the KWIC Cloud instance will use to listen for the connection from the KWIC On-Prem instance, and press Enter. For the example in the screenshot, we enter 1 and use 73.12.130.25. The IP addresses in your screen will be different. Select the IP address that is can be reached by your KWIC On-Prem instance. If you are doing this setup on two computers in your local network, the second IP address might be the one to choose as the first IP address is often the computer’s external, public IP address.

    Important: Record the IP address because you will need to enter it when configuring the KWIC On-Prem instance to connect to this KWIC Cloud instance.

    Next, you are prompted for the port number that the KWIC Cloud instance will use when listening for the connection from the KWIC On-Prem instance.

    Figure: Port number for KWIC connection
  7. Enter the port number to use for the connection and press Enter. For this example, we will use 8080. You can use that port number also.

    Important: Record the port number because you will need to enter it when configuring the KWIC On-Prem instance to connect to this KWIC Cloud instance.

    Next, the proxy service screen appears.

    Figure: KWIC Cloud Proxy Service

    Why am I doing this? We are configuring the KWIC Cloud instance to proxy messages from a cloud client to an on-prem server, as shown in bold here:

    client -> KWIC Cloud -> web -> KWIC On-Prem -> server

    The KWIC Could instance needs to know what IP address and port to listen on for client communications. It will then proxy these communications to the KWIC On-Prem instance which forwards them to the on-prem server.

  8. Select the option KWIC Cloud: Listen for a client in the cloud (most common) by typing 1, and then press Enter. You are then prompted to enter a name for the proxy service.

    Figure: KWIC Cloud Proxy Service Name

    Why am I doing this? Both the KWIC Cloud and On-Prem instances will use KWIC proxy services to proxy communication between the cloud client and on-prem server. (This is not an HTTP proxy and does not perform the same function.) The KWIC proxy services on both the KWIC Cloud and On-Prem instances use the same name to make it easier to identify them when looking at the configuration files. The name may be formatted using the ASCII letters 'a' through 'z' (in a case-insensitive manner), the digits '0' through '9', and the minus sign ('-').

  9. Enter a name for the proxy service and press Enter. For this example, we will use the name serviceA.

    Important: Record the proxy service name you entered. You will need to use the same name when you configure the corresponding KWIC proxy service on the KWIC On-Prem instance.

    Next, you are prompted for the port number on which the KWIC Cloud instance will listen for the cloud-based client.

    Figure: KWIC Cloud Proxy Port Number

    Why am I doing this? You are not prompted for an IP address, just a port number because the KWIC setup tool configures the KWIC Cloud instance to listen for cloud-based clients on the IP address 0.0.0.0. This means the KWIC Cloud will listen on all its IPv4 addresses. (This IP address simplifies setup, but you will likely change it to a specific IP address for production.)

  10. Enter the port number that the KWIC Cloud instance will use to accept a client connection, and press Enter. For this example, we will use the number 5551.

    The KWIC Cloud instance configuration is displayed, with the KWIC Cloud IP address and port number displayed at the top of the screen and the KWIC proxy service information displayed under Proxy Service Details.

    Figure: KWIC Cloud Instance Details

    Important: If you haven’t already, record the KWIC IP Address, KWIC Port, and proxy service name. You will need this information when you configure the KWIC On-Prem instance to connect to the KWIC Cloud instance.

    Your KWIC Cloud instance is now configured to establish a KWIC connection with a KWIC On-Prem instance, and to accept connections from a cloud client.

  11. Enter m to return to the main menu.
  12. Enter q to quit the setup tool. The KWIC Cloud instance is now configured to listen for a client connection and a KWIC On-Prem connection and proxy communication between them. If you look in the KWIC Cloud configuration file, located at KWIC_HOME/conf/kwic-config.xml, you will see the following proxy service configuration (comments added):

    <service>
      <!-- The name of the proxy service -->
      <name>serviceA</name>
      <!-- The KWIC Cloud listens on all interfaces for a client connection -->
      <accept>tcp://0.0.0.0:5551</accept>
      <!-- The URL where KWIC Cloud listens for the KWIC On-Prem connection -->
      <connect>pipe://serviceA</connect>
     
      <type>proxy</type>
     
      <connect-options>
        <tcp.bind>8080</tcp.bind>
        <!-- The URL used as the transport layer between the Cloud and KWIC On-Prem instances -->
        <pipe.transport>socks://73.12.130.25:8080</pipe.transport>
        <socks.mode>reverse</socks.mode>
        <socks.transport>wsn://73.12.130.25:8080/kwic</socks.transport>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </connect-options>
    </service>
    

    For more information about the configuration elements, see KWIC 5 Configuration Files.

  13. Start your KWIC Cloud instance. Go to KWIC_HOME/bin and run ./kwic.start (kwic.start.exe on Windows as administrator). If you use a port number lower than 1024, you will need to use system administrator credentials (sudo). You will see an output similar to the following:

    INFO  Kaazing KWIC
    INFO  Configuration file: kwic-5.6.2/conf/kwic-config.xml
    INFO  Checking license information
    INFO    No valid Kaazing license found
    INFO  Using Kaazing developer license, maximum 100 connections
    INFO  Starting server
    INFO  Starting services
    INFO    http://127.0.0.1:8080/ @ 0.0.0.0:8080
    INFO    http://73.12.130.25:8080/ @ 0.0.0.0:8080
    INFO    http://localhost:8080/ @ 0.0.0.0:8080
    INFO    tcp://0.0.0.0:5551
    INFO  Started services
    INFO  Started server successfully in 1.818 secs at 2017-07-14 16:00:46
    

Walkthrough 1 - Set Up KWIC On-Prem Instance

To set up the KWIC On-Prem instance, do the following:

  1. Log into the machine you are using for the KWIC On-Prem instance. Ensure the system meets the system requirements.
  2. Download the KWIC distribution package from https://kaazing.com/download/#kwic.
  3. Unpack the compressed download of KWIC to any directory location and then rename it as necessary (for example, you could rename it to C:\kwic, C:\kwic-on-prem or /home/username/kwic-on-prem). The top-level directory for KWIC is represented in this document as KWIC_HOME because the actual directory destination depends on your operating system.
  4. From the command-line, run the KWIC setup tool, kwic.setup (kwic.setup.exe on Windows), located in KWIC_HOME. Here is the welcome screen:
    Figure: KWIC Setup Welcome Screen

    You will now configure the KWIC On-Prem instance. This involves configuring the KWIC On-Prem instance to connect to the KWIC Cloud instance and the on-prem server, as shown in the bolded section of this topology:

    client -> KWIC Cloud <- web <- KWIC On-Prem -> server

  5. On the first screen of the KWIC setup tool, enter o to select the On-Prem instance, and press Enter. The KWIC On-Prem instance screen appears.

    Figure: KWIC On-Prem Instance
  6. Enter 1 to select the option to Connect to an On-Prem server, and press Enter. You are then prompted to enter a name for the KWIC proxy service.

    Why am I doing this? Both the KWIC Cloud and On-Prem instances proxy communication between a cloud client and on-prem server. Both KWIC instances use the same name for the KWIC proxy service in order to identify the connection that uses the service.

  7. Enter the same proxy service name you used when you configured the proxy service on the KWIC Cloud instance, and press Enter. For this example, we used the name serviceA. You are then asked for the hostname or IP address of the on-prem server.

    Figure: On-prem server Hostname or IP

    Why am I doing this? The KWIC On-Prem instance must be able to locate the on-prem server in order to proxy communication between the on-prem server and the KWIC Cloud instance. The KWIC On-Prem instance can locate the on-prem server using an IP address or by resolving a hostname using your corporate network’s DNS server.

  8. Enter the IP address or hostname of the on-prem server (Endpoint) that you want the KWIC On-Prem instance to connect with, and press Enter. For this example, we will use localhost because we will use the same physical server for the KWIC On-Prem instance and the simulated on-prem server.

    You are then asked for the port number to use for the KWIC On-Prem instance to connect to the on-prem server.

    Figure: Port Number for On-prem Server Connection

    Why am I doing this? The on-prem server will be configured to accept connections from the KWIC On-Prem instance at a specific port number. The KWIC On-Prem instance requires this port number in order to connect to the on-prem server.

  9. Enter the port number 5552, and click Enter. You are then asked for the IP address of the KWIC Cloud instance.

    Figure: IP Address of the KWIC Cloud Instance

    Why am I doing this? The KWIC On-Prem instance needs the IP address of the KWIC Cloud instance in order to connect to it and establish the KWIC connection and for future communication. This is the same IP address you entered when configuring the KWIC Cloud instance to listen for the KWIC On-Prem instance. In our screenshot, we used 73.12.130.25, but your IP address will be different.

  10. Enter the IP address for the KWIC On-Prem instance to use when connecting to the KWIC Cloud instance, and then press Enter. You are then asked for the port number to use for the connection to the KWIC Cloud instance.

    Figure: IP Address for KWIC Connection

    Why am I doing this? In addition to the IP address of the KWIC Cloud instance, the KWIC On-Prem needs to the port number of the port the KWIC Cloud instance is listening on for the KWIC On-Prem connection. This is the same port number you entered when configuring the KWIC Cloud instance to listen for the KWIC On-Prem instance. For this example, we are using 8080.

  11. Enter the port number 8080 for the connection to the KWIC Cloud instance, and press Enter. The proxy configuration is displayed.

    Figure: KWIC On-Prem Proxy Details

    Your KWIC On-Prem instance is now configured to establish a KWIC connection with a KWIC Cloud instance, and to proxy communication with an on-prem server.

  12. Enter m to return to the main menu, and then press Enter.
  13. Enter q to quit the setup tool. The KWIC On-Prem instance is now configured to listen for an on-prem server connection and to connect to a KWIC Cloud instance and proxy communication between them. If you look in the KWIC On-Prem configuration file, located at KWIC_HOME/conf/kwic-config.xml, you will see the following proxy service configuration (comments added):

    <service>
      <name>serviceA</name>
      <!-- The URL to connect to the KWIC Cloud instance-->
      <accept>pipe://serviceA</accept>
      <!-- The URL to connect to the on-prem server -->
      <connect>tcp://localhost:5552</connect>
    
      <type>proxy</type>
     
      <accept-options>
        <tcp.bind>8080</tcp.bind>
        <!-- The URL used as the transport layer between the Cloud and KWIC On-Prem instances -->
        <pipe.transport>socks://73.12.130.25:8080</pipe.transport>
        <socks.mode>reverse</socks.mode>
        <socks.transport>ws://73.12.130.25:8080/kwic</socks.transport>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </accept-options>
    </service>
    
  14. Start your KWIC On-Prem instance. Go to KWIC_HOME/bin and run ./kwic.start (kwic.start.exe on Windows as administrator). You will see an output similar to the following:

    INFO  Kaazing KWIC
    INFO  Configuration file: kwic-5.6.2/conf/kwic-config.xml
    INFO  Checking license information
    INFO    No valid Kaazing license found
    INFO  Using Kaazing developer license, maximum 100 connections
    INFO  Starting server
    INFO  Starting services
    INFO    http://0.0.0.0:8080/
    INFO    http://127.0.0.1:8080/ @ 0.0.0.0:8080
    INFO    http://localhost:8080/ @ 0.0.0.0:8080
    INFO    pipe://serviceA
    INFO  Started services
    INFO  Started server successfully in 0.690 secs at 2017-07-14 16:08:06
    

    When the KWIC On-Prem instance connects to the KWIC Cloud instance, you will see output indicating the connection. For example:

    DEBUG Reverse connection ready: pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:58167
    DEBUG Proxy accepted for "serviceA": accept=[pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:58167, remote=73.12.130.25:8080], connect=[tcp://localhost:5552, local=127.0.0.1:58171, remote=127.0.0.1:5552]
    

    On the KWIC Cloud instance, you will see corresponding information that shows that the KWIC connection is running. For example:

    DEBUG Reverse connection ready: pipe://servicea via wsn://73.12.130.25:8080/kwic, remote=12.203.64.50:2409
    DEBUG Proxy accepted for "serviceA": accept=[tcp://0.0.0.0:5551, local=127.0.0.1:5551, remote=127.0.0.1:53364], connect=[pipe://servicea via wsn://73.12.130.25:8080/kwic, local=127.0.0.1:8080, remote=12.203.64.50:2409]
    

    Note: If you do not see the connection output, see KWIC 5 Logging and Troubleshooting.

    Next, test your client to server KWIC connection using the steps in Walkthrough 1 - Verifying KWIC Deployment.

Let’s look the KWIC Cloud and KWIC On-Prem configuration files side-by-side to see how the KWIC connection (pipe) and proxies work together:

KWIC Cloud Configuration KWIC On-Prem Configuration
<service>
  <name>serviceA</name>
  <accept>tcp://0.0.0.0:5551</accept>
  <connect>pipe://serviceA</connect>
 
  <type>proxy</type>
 
  <connect-options>
    <tcp.bind>8080</tcp.bind>
    <pipe.transport>socks://73.12.130.25:8080</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.transport>wsn://73.12.130.25:8080/kwic</socks.transport>
    <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
  </connect-options>
</service>
<service>
  <name>serviceA</name>
  <accept>pipe://serviceA</accept>
  <connect>tcp://localhost:5552</connect>

  <type>proxy</type>
 
  <accept-options>
    <tcp.bind>8080</tcp.bind>
    <pipe.transport>socks://73.12.130.25:8080</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.transport>ws://73.12.130.25:8080/kwic</socks.transport>
    <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
  </accept-options>
</service>

Here you can see the following:

Walkthrough 1 - Verifying KWIC Deployment

Verifying your KWIC setup involves sending a client message to the KWIC Cloud instance, having that message proxied to the on-prem server via the KWIC On-Prem instance, and having the message displayed by the on-perm server.

For this setup, we will use just two computers in order to simplify the test:

The cloud client and on-prem servers are simulated using the kwic.test tool included in the KWIC distribution (KWIC_HOME/bin folder). If you choose to test your setup using separate computers for the cloud client and on-prem server, copy kwic.test to those machines.

Note: The kwic.test tool verifies end-to-end connectivity between a single endpoint client and a single endpoint server. It is not intended to verify multiple, simultaneous client to server connections.

To verify the running KWIC setup you configured, do the following:

  1. Ensure both the KWIC Cloud and On-Prem instances are running as described in steps Start your KWIC Cloud instance and Start your KWIC On-Prem instance.

    Why am I doing this? When you start the KWIC On-Prem instance it will connect to the KWIC Cloud instance to establish the KWIC connection. This all happens in the background. If the there is an error in the command prompt, see KWIC 5 Logging and Troubleshooting.

  2. On the KWIC On-Prem server, from the command-line, locate the kwic.test program in the KWIC_HOME/bin folder. You will start kwic.test as a test server and listen on all IP addresses.
  3. Run kwic.test from the command-line by entering the following:

    kwic.test -l 5552

    Why am I doing this? Now this on-prem server is listening for client connections on all interfaces at port 5552. This is the port number we used to connect the KWIC On-Prem instance to the on-prem server. (You can find this in the configuration file as follows: <connect>tcp://localhost:5552</connect>.)

  4. On the KWIC Cloud server, from the command-line, locate the kwic.test program on the KWIC_HOME/bin folder. You will start kwic.test as a test client send a message via the KWIC connection to the the on-prem server.
  5. Run kwic.test from the command-line by entering the IP address and port number that the KWIC instance is using to listen for client connections, 127.0.0.1 5551:

    kwic.test 127.0.0.1 5551

    Why am I doing this? The KWIC Cloud instance has a KWIC proxy service listening at tcp://0.0.0.0:5551. (You can find this in the configuration file as follows: <accept>tcp://0.0.0.0:5551</accept>.) This is the IP address and port number we used for the KWIC Cloud instance to listen for client connections. The KWIC Cloud instance is listening on all interfaces and you simply need the IP address of one interface. In this case, because the simulated client is one the same computer as the KWIC Cloud instance, we can use the loopback address 127.0.0.1 and port number 5551.

  6. In the client kwic.test, type a message, such as Hello, KWIC, and press Enter.
  7. In the server kwic.test, see that the message has arrived. If the message does not arrive, see KWIC 5 Logging and Troubleshooting.

Walkthrough 2 - On-Prem Clients Connecting to Cloud Servers

There are two steps in setting up a KWIC deployment:

  1. Connect the KWIC On-Prem instance and the KWIC Cloud instance. This is established with an outbound connection from the KWIC On-Prem instance to the KWIC Cloud instance. The KWIC connection setup can be summarized like this:

    client | KWIC Cloud <- web <- KWIC On-Prem | server

    The | symbol is used to indicate that the cloud client and on-prem server have not yet communicated over the KWIC connection.

  2. Connect the on-prem client to the cloud server over the KWIC connection. The client-server connection can be summarized like this:

    server <- KWIC Cloud <- web <- KWIC On-Prem <- client

Walkthrough 2 - Setup Overview

This walkthrough has the following sections and steps to perform:

  1. Set Up KWIC Cloud Instance.
    1. Download KWIC.
    2. Enter the IP address and port the KWIC Cloud instance will use to listen for the KWIC On-Prem instance
    3. Enter a KWIC proxy service name. The KWIC Cloud proxy service will proxy cloud server communications to the KWIC On-Prem instance.
    4. Enter the IP address and port number of the cloud server for the KWIC Cloud instance to connect with.
    5. Start the KWIC Cloud instance.
  2. Set Up KWIC On-Prem Instance.
    1. Download KWIC.
    2. Enter the same KWIC proxy service name you used when configuring the KWIC Cloud proxy.
    3. Enter the port number that the on-prem client will use when it communicates with the KWIC On-Prem instance.
    4. Enter the hostname or IP address, and port number, of the KWIC Cloud instance. This enables the KWIC On-Prem instance to initiate the outbound connection to the KWIC Cloud instance and establish the KWIC connection.
    5. Start the KWIC On-Prem instance.
  3. Verifying KWIC Deployment for Walkthrough 2.
    1. Simulate a cloud server on the same server running the KWIC Cloud instance.
    2. Simulate a on-prem client on the same server running the KWIC On-Prem instance.
    3. Send a message from the client to the server, and verify that it arrived.

Walkthrough 2 - Set Up KWIC Cloud Instance

To configure the KWIC Cloud instance, do the following:

  1. Log into the machine you are using for the KWIC Cloud server. Ensure the system meets the system requirements.
  2. Download the KWIC distribution package from https://kaazing.com/download/#kwic.
  3. Unpack the compressed download of KWIC to any directory location and then rename it as necessary (for example, you could rename it to C:\kwic, C:\kwic-cloud or /home/username/kwic-cloud). The top-level directory for KWIC is represented in this document as KWIC_HOME because the actual directory destination depends on your operating system.
  4. From the command-line, run the KWIC setup tool, kwic.setup (kwic.setup.exe on Windows), located in KWIC_HOME. Here is the welcome screen:

    Figure: kwic.setup Welcome Screen

    You will now configure the KWIC Cloud instance. This involves configuring the KWIC Cloud instance to listen for connections from the KWIC On-Prem instance and the cloud server, as shown in the bolded section of this topology:

    server -> KWIC Cloud <- web <- KWIC On-Prem -> client
  5. On the first screen of KWIC setup tool, choose Set up a Cloud instance by typing c, and then press Enter. The KWIC Cloud Instance setup screen appears:

    Figure: KWIC Cloud Instance Setup Screen

    In this screen you will select the IP address and port number that the KWIC Cloud instance will use to listen for a connection from the KWIC On-Prem instance.

    Why am I doing this? Later in this walkthrough you will set up and start the KWIC On-Prem instance. When the KWIC On-Prem instance starts, it contacts the KWIC Cloud instance to establish the KWIC connection. The connection attempt looks like this:

    KWIC Cloud <-- web <-- KWIC On-Prem

    The KWIC On-Prem instance contacts the KWIC Cloud instance using a specific IP address and port number, and so you need to configure the KWIC Cloud instance to listen on that IP address and port number.

  6. From the list of available IP addresses, enter the number next to the IP address that the KWIC Cloud instance will use to listen for the connection from the KWIC On-Prem instance, and press Enter. For the example in the screenshot, we enter 1 and use 73.12.130.25. The IP addresses in your screen will be different. Select the IP address that is can be reached by your KWIC On-Prem instance. If you are doing this setup on two computers in your local network, the second IP address might be the one to choose as the first IP address is often the computer’s external, public IP address.

    Important: Record the IP address because you will need to enter it when configuring the KWIC On-Prem instance to connect to this KWIC Cloud instance. Next, you are prompted for the port number that the KWIC Cloud instance will use when listening for the connection from the KWIC On-Prem instance.
    Figure: Port Number for KWIC Connection
  7. Enter the port number to use for the connection and press Enter. For this example, we will use 8080. You can use that port number also.

    Important: Record the port number because you will need to enter it when configuring the KWIC On-Prem instance to connect to this KWIC Cloud instance.

    Next, the proxy selection screen appears.

    Figure: KWIC Cloud Proxy Selection

    Why am I doing this? We are configuring the KWIC Cloud instance to proxy messages from an on-prem client to a cloud server, as shown in bold here:

    server <- KWIC Cloud <- web <- KWIC On-Prem <- client

    The KWIC Could instance needs to know what IP address and port to listen on for cloud server communications. It will then proxy these communications to the KWIC On-Prem instance which forwards them to the on-prem client.

  8. Select the option KWIC Cloud: Connect to a server in the cloud by typing 2, and then press Enter. You are then prompted to enter a name for the proxy service.

    Figure: Proxy Service Name

    Why am I doing this? Both the KWIC Cloud and On-Prem instances will use KWIC proxy services to proxy communication between the on-prem client and cloud server. (This is not an HTTP proxy and does not perform the same function.) The KWIC proxy services on both the KWIC Cloud and On-Prem instances use the same name to make it easier to identify them when looking at the configuration files. The name may be formatted using the ASCII letters 'a' through 'z' (in a case-insensitive manner), the digits '0' through '9', and the minus sign ('-').

  9. Enter a name for the proxy service and press Enter. For this example, we will use the name serviceB.

    Important: Record the proxy service name you entered. You will need to use the same name when you configure the corresponding KWIC proxy service on the KWIC On-Prem instance.

    Next, you are prompted for the hostname or IP address of the cloud-based server.

    Figure: Cloud-Based Server Hostname or IP

    Why am I doing this? The KWIC Cloud instance needs the hostname or IP address of the cloud server in order to send the server communications from the on-prem client. For this example, we will use the hostname localhost because we will be running a simulated cloud server on the same computer as the KWIC Cloud instance. In production, the hostname would be for a different computer and the KWIC Cloud must be able to resolve this hostname using DNS.

  10. Enter localhost and press Enter. Next, you are asked for the port number of the connection to the cloud server. This is port number on which the cloud server is listening for communications from clients.
  11. Enter 6662 and press Enter.

    The KWIC Cloud instance configuration is displayed, with the KWIC Cloud IP address and port number displayed at the top of the screen and the KWIC proxy service information displayed under Proxy Service Details.

    Figure: Cloud Instance Proxy Service Details
    Important: If you haven’t already, record the KWIC IP Address, KWIC Port, and proxy service name. You will need this information when you configure the KWIC On-Prem instance to connect to the KWIC Cloud instance.

    Your KWIC Cloud instance is now configured to establish a KWIC connection with a KWIC On-Prem instance, and to communicate with a cloud server.

  12. Enter m to return to the main menu.
  13. Enter q to quit the setup tool. The KWIC Cloud instance is now configured to communicate with a cloud server and a KWIC On-Prem instance and proxy communication between them. If you look in the KWIC Cloud configuration file, located at KWIC_HOME/conf/kwic-config.xml, you will see the following proxy service configuration (comments added):

    <service>
      <!-- The name of the proxy service -->
      <name>serviceB</name>
      <!-- The KWIC Cloud listens on this URL for the On-Prem KWIC connection -->
      <accept>ws://73.12.130.25:8080/serviceB</accept>
      <!-- The KWIC Cloud connects to the cloud server using this URL -->
      <connect>tcp://localhost:6662</connect>
     
      <type>proxy</type>
     
      <accept-options>
        <tcp.bind>8080</tcp.bind>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </accept-options>
    </service>
    

    For more information about the configuration elements, see KWIC 5 Configuration Files.

  14. Start your KWIC Cloud instance. Go to KWIC_HOME/bin and run ./kwic.start (kwic.start.exe on Windows as administrator). If you use a port number lower than 1024, you will need to use system administrator credentials (sudo). You will see an output similar to the following:

    INFO  Kaazing KWIC
    INFO  Configuration file: kwic-5.6.2/conf/kwic-config.xml
    INFO  Checking license information
    INFO    No valid Kaazing license found
    INFO  Using Kaazing developer license, maximum 100 connections
    INFO  Starting server
    INFO  Starting services
    INFO    http://127.0.0.1:8080/ @ 0.0.0.0:8080
    INFO    http://73.12.130.25:8080/ @ 0.0.0.0:8080
    INFO    http://localhost:8080/ @ 0.0.0.0:8080
    INFO    ws://73.12.130.25:8080/serviceB
    INFO  Started services
    INFO  Started server successfully in 0.471 secs at 2017-07-17 14:51:38
    

Walkthrough 2 - Set Up the KWIC On-Prem Instance

To set up the KWIC On-Prem instance, do the following:

  1. Log into the machine you are using for the KWIC On-Prem instance. Ensure the system meets the system requirements.
  2. Download the KWIC distribution package from https://kaazing.com/download/#kwic.
  3. Unpack the compressed download of KWIC to any directory location and then rename it as necessary (for example, you could rename it to C:\kwic, C:\kwic-on-prem or /home/username/kwic-on-prem). The top-level directory for KWIC is represented in this document as KWIC_HOME because the actual directory destination depends on your operating system.
  4. From the command-line, run the KWIC setup tool, kwic.setup (kwic.setup.exe on Windows), located in KWIC_HOME. Here is the welcome screen:

    Figure: KWIC Setup Welcome

    You will now configure the KWIC On-Prem instance. This involves configuring the KWIC On-Prem instance to connect to the KWIC Cloud instance and accept connections from the on-prem client, as shown in the bolded section of this topology:

    server <- KWIC Cloud <- web <- KWIC On-Prem <- client

  5. On the first screen of the KWIC setup tool, enter o to select the On-Prem instance, and press Enter. The KWIC On-Prem instance screen appears.

    Figure: KWIC On-Prem Instance Options
  6. Enter 2 to select the option to Listen for an On-Prem client, and press Enter. You are then prompted to enter a name for the KWIC proxy service.

    Why am I doing this? Both the KWIC Cloud and On-Prem instances proxy communication between an on-prem client and a cloud server. Both KWIC instances use the same name for the KWIC proxy service in order to identify the connection that uses the service.

  7. Enter the same proxy service name you used when you configured the proxy service on the KWIC Cloud instance, and press Enter. For this example, we used the name serviceB. You are then asked for the port number that the KWIC On-Prem will listen on for the on-prem client connections.

    Why am I doing this? You are not prompted for an IP address, just a port number because the KWIC setup tool configures the KWIC On-Prem instance to listen for on-prem clients on the IP address 0.0.0.0. This means the KWIC On-Prem instance will listen on all its IPv4 addresses. (This IP address simplifies setup, but you will likely change it to a specific IP address for production.)

  8. Enter the port number that the KWIC On-Prem instance will use to accept a client connection, and press Enter. For this example, we will use the number 6661. You are then asked for the KWIC Cloud instance IP address.

    Why am I doing this? Earlier in this walkthrough you set up the KWIC Cloud instance to listen for the connection from KWIC On-Prem instance at a specific IP address and port number. When the KWIC On-Prem instance starts, it contacts the KWIC Cloud instance to establish the KWIC connection. The connection attempt looks like this:

    KWIC Cloud <-- web <-- KWIC On-Prem

    The KWIC On-Prem instance contacts the KWIC Cloud instance using a specific IP address and port number, and so you need to configure the KWIC On-Prem instance to connect on that IP address and port number.

    Next, you are asked for the IP address of the KWIC Cloud instance.

    Figure: Enter the IP address of the KWIC Cloud instance

    Why am I doing this? Earlier in this walkthrough you set up the KWIC Cloud instance. When the KWIC On-Prem instance starts, it contacts the KWIC Cloud instance to establish the KWIC connection. The connection attempt looks like this:

    KWIC Cloud <-- web <-- KWIC On-Prem

    The KWIC On-Prem instance contacts the KWIC Cloud instance using a specific IP address and port number, and so you need to configure the KWIC Cloud instance to listen on that IP address and port number.

  9. Enter the same IP address you used when configuring the IP address the KWIC Cloud instance will listen on for connections from the KWIC On-Prem instance, and then press Enter. In our example, we used the IP address 73.12.130.25. Your IP address will be different.

    Next, you are asked for the port number for the connection to the KWIC Cloud instance.

    Figure: KWIC Connection Port Number
  10. Enter the same port number you entered when configuring the port number the KWIC Cloud instance will listen on for connections from the KWIC On-Prem instance, and then press Enter. In our example, we used 8080. You can use the same port number. The proxy configuration is displayed.

    Figure: On-Prem Instance Proxy Service Details

    Your KWIC On-Prem instance is now configured to establish a KWIC connection with a KWIC Cloud instance, and to proxy communication with an on-prem client.

  11. Enter m to return to the main menu, and then press Enter.
  12. Enter q to quit the setup tool. The KWIC On-Prem instance is now configured to listen for an on-prem client connection and to connect to a KWIC Cloud instance and proxy communication between them. If you look in the KWIC On-Prem configuration file, located at KWIC_HOME/conf/kwic-config.xml, you will see the following proxy service configuration (comments added):

    <service>
      <!-- The name of the proxy service -->
      <name>serviceB</name>
      <!-- The URI that the On-Prem KWIC listen for a client connection -->
      <accept>tcp://0.0.0.0:6661</accept>
      <!-- The URL the On-Prem uses to connect to the KWIC Cloud -->
      <connect>ws://73.12.130.25:8080/serviceB</connect>
     
      <type>proxy</type>
     
      <connect-options>
        <http.maximum.redirects>3</http.maximum.redirects>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </connect-options>
    </service>
    
  13. Start your KWIC On-Prem instance. Go to KWIC_HOME/bin and run ./kwic.start (kwic.start.exe on Windows as administrator). You will see an output similar to the following:

    INFO  Kaazing KWIC (5.7.2)
    INFO  Configuration file: kwic-5.6.2/conf/kwic-config.xml
    INFO  Checking license information
    INFO    No valid Kaazing license found
    INFO  Using Kaazing developer license, maximum 100 connections
    INFO  Starting server
    INFO  Starting services
    INFO    http://10.0.0.142:8080/ @ 0.0.0.0:8080
    INFO    http://127.0.0.1:8080/ @ 0.0.0.0:8080
    INFO    http://localhost:8080/ @ 0.0.0.0:8080
    INFO    tcp://0.0.0.0:6661
    INFO  Started services
    INFO  Started server successfully in 0.871 secs at 2017-07-17 15:35:49
    

  14. Next, test your client to server KWIC connection using the steps in Walkthrough 2 - Verifying KWIC Deployment.

Let’s look the KWIC Cloud and KWIC On-Prem configuration files side-by-side to see how the KWIC connection and proxies work together:

KWIC Cloud Configuration KWIC On-Prem Configuration
<service>
  <name>serviceB</name>
  <accept>ws://73.12.130.25:8080/serviceB</accept>
  <connect>tcp://localhost:6662</connect>
 
  <type>proxy</type>
 
  <accept-options>
    <tcp.bind>8080</tcp.bind>
    <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
  </accept-options>
</service>
<service>
  <name>serviceB</name>
  <accept>tcp://0.0.0.0:6661</accept>
  <connect>ws://73.12.130.25:8080/serviceB</connect>
 
  <type>proxy</type>
 
  <connect-options>
    <http.maximum.redirects>3</http.maximum.redirects>
    <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
  </connect-options>
</service>

Here you can see the following:

Walkthrough 2 - Verifying KWIC Deployment

Verifying your KWIC setup involves sending a client message to the KWIC On-Prem instance, having that message proxied to the cloud server via the KWIC Cloud instance, and having the message displayed by the cloud server.

For this setup, we will use just two computers in order to simplify the test:

The cloud server and on-prem client are simulated using the kwic.test tool included in the KWIC distribution (KWIC_HOME/bin folder). If you choose to test your setup using separate computers for the client and server, copy kwic.test to those machines.

Note: The kwic.test tool verifies end-to-end connectivity between a single endpoint client and a single endpoint server. It is not intended to verify multiple, simultaneous client to server connections.

To verify the running KWIC setup you configured, do the following:

  1. Ensure both the KWIC Cloud and On-Prem instances are running.

    Why am I doing this? When you start the KWIC On-Prem instance it will connect to the KWIC Cloud instance to establish the KWIC connection. This all happens in the background. If the there is an error in the command prompt, see KWIC 5 Logging and Troubleshooting.

  2. On the KWIC Cloud server, from the command-line, locate the kwic.test program in the KWIC_HOME/bin folder. You will start kwic.test as a test server and listen on all IP addresses.
  3. Run kwic.test from the command-line by entering the following:

    kwic.test -l 6662

    Why am I doing this? Now this cloud server is listening for client connections on all interfaces at port 6661. This is the port number we used to connect the KWIC Cloud instance to the cloud server. (You can find this in the configuration file as follows: <connect>tcp://localhost:6662</connect>.)

  4. On the KWIC On-Prem server, from the command-line, locate the kwic.test program on the KWIC_HOME/bin folder. You will start kwic.test as a test client send a message via the KWIC connection to the the cloud server.
  5. Run kwic.test from the command-line by entering the IP address and port number that the KWIC On-Prem instance is using to listen for client connections, 127.0.0.1 6661:

    kwic.test 127.0.0.1 6661

    Why am I doing this? The KWIC On-Prem instance has a KWIC proxy service listening at tcp://0.0.0.0:6661. (You can find this in the configuration file as follows: <accept>tcp://0.0.0.0:6661</accept>.) This is the IP address and port number we used for the KWIC On-Prem instance to listen for client connections. The KWIC On-Prem instance is listening on all interfaces and you simply need the IP address of one interface. In this case, because the simulated client is one the same computer as the KWIC On-Prem instance, we can use the loopback address 127.0.0.1 and port number 6661.

  6. In the client kwic.test, type a message, such as Hello, KWIC, and press Enter.
  7. In the server kwic.test, see that the message has arrived. If the message does not arrive, see KWIC 5 Logging and Troubleshooting.

Note: In some instances, the KWIC connection might pass through an older proxy server that does not support WebSocket. To determine if this is an issue, open a browser on each of the connection points, and browse to websocketstest.com. The best solution to this problem is to configure the KWIC connection to use TLS as described in Production KWIC 5 and Security.

Configure KWIC to Run at System Startup

You can use the KWIC setup tool to install KWIC as a service and configure KWIC to run at system startup on your server.

Note: You will need system administrator privileges to configure KWIC to run at system startup.

To configure KWIC to run at system startup, do the following:

  1. From the command-line, run the KWIC setup tool, sudo kwic.setup (in Windows, right-click cmd, and choose Run as Administrator), located in KWIC_HOME.
  2. Enter your system administrator password.
  3. Select Configure KWIC to run at system startup (c), and press Enter. The setup tool will indicate whether the KWIC service is running:

    Configuring KWIC to run at system startup
    
    Installing KWIC as a startup service ... 
    Type of startup service is launched
    Enabling service ... 
    Confirming KWIC service started (may take a moment) ... 
    KWIC service status: running

Starting and Stopping a KWIC Instance

You might need to restart a KWIC instance if you need to change its configuration file (KWIC_HOME/conf/kwic-config.xml).

To stop a KWIC instance, do one of the following:

To restart a KWIC instance, simply run sudo ./kwic.start (kwic.start.exe on Windows as administrator) from the KWIC_HOME/bin directory.

KWIC 5 Configuration Files

This section describes the main KWIC configuration elements for the Cloud Clients Connecting to On-Prem Servers and On-Prem Clients Connecting to Cloud Servers scenarios.

Element KWIC Cloud KWIC On-Prem
proxy Proxies connections to the cloud client or cloud server. Once the connection is established, KWIC acts as a proxy for a client or server that cannot natively establish a TCP or HTTP connections over the Web. Proxies connections to the on-prem server or client. For inbound connections, the KWIC On-Prem instance proxies connections using WebSocket and a reverse proxy (SOCKS). For outbound connections, the KWIC On-Prem 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 KWIC On-Prem instance. In a reverse connection, a pipe:// scheme is used and the On-Prem KWIC instance accepts connections from the KWIC hub at the URL in accept. The pipe:// scheme is a URI scheme internal to KWIC and used to create a named, logical channel between the Cloud and KWIC On-Prem instances. With KWIC, one end of the pipe is in the KWIC Cloud, and the other end of the pipe is the KWIC On-Prem. The pipe.transport element is where the transport is set to SOCKet Secure (SOCKS) over WebSocket (for example: <pipe.transport>socks://ServiceHostName</pipe.transport>).
connect The URL of a service to which the proxy service connects. In a reverse connection, a pipe:// scheme is used and the KWIC Cloud instance connects to the On-Prem KWIC instance at this URL. In a forward connection, a tcp:// scheme is typically used and the KWIC Cloud instance connects to the cloud server at this URL. In a reverse connection, a tcp:// scheme typically is used and the KWIC On-Prem instance connects to an on-prem server at this URL. In a forward connection, a WebSocket scheme is used to connect to the KWIC Cloud instance.
accept-options In a forward connection, the KWIC 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 KWIC On-Prem 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 KWIC 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 KWIC On-Prem 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 KWIC On-Prem instances. This setting is not used in a forward connection. In a reverse connection, this setting is identical between the Cloud and KWIC On-Prem proxy services.
socks.mode Initiates a connection using the SOCKet Secure (SOCKS) protocol. The value of reverse initiates the connection from the KWIC On-Prem instance to the KWIC Cloud instance. The connection initiates outwards from behind the on-prem firewall. This setting is not used in a forward connection. In a reverse connection, this setting is identical between the Cloud and KWIC On-Prem 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 KWIC On-Prem proxy services.
ws.inactivity.timeout Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval syntax). The Cloud and KWIC On-Prem instances will drop the connection if either cannot communicate with the other in the number of seconds specified. You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed. In a reverse connection, this setting is identical between the Cloud and KWIC On-Prem proxy services.
socks.ssl.verify-client For reverse connections, the socks.ssl.verify-client on a connect specifies that the KWIC Cloud instance requires that the KWIC On-Prem instance provide a client digital certificate that the KWIC Cloud instance can use to verify the KWIC On-Prem instance’s identity. This element is not used by the KWIC On-Prem instance.
ssl.verify-client For a forward connection, the ssl.verify-client on an accept specifies that the KWIC Cloud instance requires that the KWIC On-Prem instance provide a client digital certificate that the KWIC Cloud instance can use to verify the KWIC On-Prem instance’s identity. This element is not used by the KWIC On-Prem instance.
property

You can use this element to specify default values for configuration elements. Configuring property defaults is optional but recommended because configuring the property defaults allows you to define some property values once and have the value propagated throughout the configuration when the KWIC 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}). For example:

<properties>
  <property>
    <name>base.port</name>
    <value>5551</value>
  </property>
</properties>
This element is used the same on all KWIC instance types.

KWIC Proxy Service Configuration Example

The following configuration shows the proxy services for both the Cloud and KWIC On-Prem instances side-by-side in order to see how the settings relate to each other.

Cloud Client to On-Prem Server Configurations (Reverse Connection)

The highlighted pipe:// connection shows how the KWIC instances are connected, and the highlighted, identical connect-options and accept-options show how the pipe transport layer.

KWIC Cloud Proxy Service KWIC On-Prem Proxy Service
<service>
 <name>serviceA</name>

 <accept>tcp://0.0.0.0:5551</accept>
 <connect>pipe://serviceA</connect>

 <type>proxy</type>

 <connect-options>
   <tcp.bind>8080</tcp.bind>
   <pipe.transport>socks://example.com</pipe.transport>
   <socks.mode>reverse</socks.mode>
   <socks.transport>ws://example.com/kwic</socks.transport>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
 </connect-options>
</service>
<service>
 <name>serviceA</name>

 <accept>pipe://serviceA</accept>
 <connect>tcp://server-a:5552</connect>

 <type>proxy</type>

 <accept-options>
   <tcp.bind>8080</tcp.bind>
   <pipe.transport>socks://example.com</pipe.transport>
   <socks.mode>reverse</socks.mode>
   <socks.transport>ws://example.com/kwic</socks.transport>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
 </accept-options>
</service>

On-Prem Client to Cloud Server Configurations (Forward Connection)

The highlighted ws:// connection shows how the KWIC instances are connected and ws.inactivity.timeout specifies the maximum number of seconds that the KWIC connection can be inactive.

KWIC Cloud Proxy Service KWIC On-Prem Proxy Service
<service>
 <name>proxy service B</name>

 <accept>ws://example.com:8080/serviceB</accept>
 <connect>tcp://server-b:6661</connect>

 <type>proxy</type>

 <accept-options>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
 </accept-options>
</service>
<service>
 <name>proxy service B</name>

 <accept>tcp://0.0.0.0:6662</accept>
 <connect>ws://example.com:80/serviceB</connect>

 <type>proxy</type>

 <connect-options>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
 </connect-options>
</service>

Production KWIC 5 and Security

The production deployment of KWIC 5 is secured using TLS/SSL between the KWIC Cloud and the KWIC On-Prem servers when the KWIC connection is established. Once a secure KWIC connection is established, you can deploy an additional end-to-end secure TLS connection between the clients and servers that use the KWIC connection. Here is an example of TLS securing the connection between the KWIC 5 instances:

Figure: KWIC TLS Connection

A KWIC TLS connection uses mutual authentication, with both the KWIC Cloud and On-Prem instances requesting and providing digital certificates to each other. The TLS connection is established in two major steps:

  1. When the KWIC On-Prem instance is started, it initiates a connection to the running KWIC Cloud server and the KWIC On-Prem instance requests a server certificate from the hostname of the KWIC Cloud instance and validates it.
  2. The KWIC Cloud instance then requests a client certificate from the KWIC On-Prem server. The KWIC On-Prem server provides a client certificate and the KWIC Cloud server validates it.

The connection in the above example is now secured by TLS in both directions. When clients and server use the KWIC connection their network traffic is encrypted by the KWIC TLS connection. If the clients and servers encrypt their own data--which is always recommended--their data is encrypted a second time by the KWIC TLS connection.

Important: Please use two-way trust. While you can choose to have one-way trust between the KWIC Cloud and the KWIC On-Prem servers, it is recommended that you deploy two-way trust by having both the KWIC Cloud and the KWIC On-Prem servers present certificates.

Note: The TLS KWIC certificates and keys (stored in their keystores and truststores) can be configured using the standard Java keytool utility that is part of your Java installation. It can be found in the %JAVA_HOME%\bin directory. For example, C:\Program Files\Java\jdk_number\bin (Windows) or /Library/Java/home/bin (Mac OS X). A useful GUI-based tool for Windows and Mac is available at keystore-explorer.org.

TLS Setup Overview

The following steps provide a high-level overview of the TLS setup procedure for reverse and forward connections:

Notes:

TLS Setup for Cloud Client to On-Prem Server Configurations (Reverse Connection)

To deploy a secure TLS KWIC connection, do the following:

  1. On the KWIC Cloud server, add a trusted certificate for the KWIC Cloud server hostname to the KWIC Cloud server keystore. This is the certificate that will be presented to the KWIC On-Prem server.
    1. Create a private key for the hostname the KWIC Cloud server (such as example.com). For example (substitute your KWIC_HOME and password in the example):

      keytool -genkeypair -alias example.com -keysize 2048 -keyalg RSA -keystore "KWIC_HOME\conf\keystore.db" -storetype JCEKS -storepass password

      You will be prompted to provide information about your organization. This information is used to verify the CSR in the future. The password value for -storepass is located in the keystore password file that is located in the KWIC_HOME/conf folder (by default, keystore.pw). You can open the file with a text editor to read the default password and enter it in the command.

    2. Create a Certificate Signing Request (CSR) for the hostname used in the proxy service of the KWIC Cloud instance. A trusted certificate is obtained by creating a CSR and sending that request to a public Certificate Authority, such as Symantec, Thawte, and Entrust, or to a Certificate Authority that is already configured in your corporate network, such as a Windows Domain Controller running as a Certificate Authority. A CSR is a public key generated on the server running KWIC that validates information about the server and your organization when you request a certificate.

      Most ISPs provide information on how to create a CSR specifically for their use. For example, see SSL Certificates Help from GoDaddy or Generate a Certificate Signing Request (CSR) from Symantec. Consult your ISP for specific CSR requirements.

      Generate the CSR using the same alias as you used when creating the private key:

      keytool -certreq -alias example.com -file certreq.txt -keystore "KWIC_HOME\conf\keystore.db" -storetype JCEKS -keyalg RSA -storepass password

      A text file containing the CSR is stored in the same folder as keystore.db.

    3. Send the CSR text file to the trusted Certificate Authority. The Certificate Authority will return a trusted certificate that you can import into the keystore. In the case of public Certificate Authorities, you will likely need to perform some kind of offline identity verification.
    4. Import the trusted certificate for the KWIC Cloud server into the keystore used by the KWIC Cloud server. The following example shows how to import the trusted certificate (example.cer) into the default keystore (keystore.db) located in KWIC_HOME/conf.

      keytool -importcert -keystore KWIC_HOME\conf\keystore.db -storetype JCEKS -storepass password -alias example.com -file example.cer

      The KWIC Cloud server is now configured with a certificate, and you can use the hostname to accept secure connections over HTTPS or WSS.

  2. Add the security element to the KWIC Cloud configuration file, KWIC_HOME/conf/kwic-config.xml. The security element identifies where the digital certificate and password file are located. You also include the truststore information so that the KWIC Cloud can locate the truststore and add the client certificate from the KWIC On-Prem server (which we will configure later). For example:
    <security>
      <keystore>
        <!-- The Java keystore type -->
        <type>JCEKS</type>
        <!-- The location of the keystore file -->
        <file>KWIC_HOME/conf/keystore.db</file>
        <!-- The location of the file containing the password for the keystore -->
        <password-file>KWIC_HOME/conf/keystore-cloud.pw</password-file>
      </keystore>
      <truststore>
        <!-- The location of the truststore file -->
        <file>KWIC_HOME/conf/truststore.db</file>
      </truststore>
    </security>
    
  3. Update the URL in the pipe.transport and socks.transport elements in the proxy service to use a secure URL and hostname. For example, when you first created the proxy service using the KWIC setup tool, the pipe.transport and socks.transport URLs were something like this:

    <connect-options>
      <tcp.bind>8080</tcp.bind>
      <pipe.transport>socks://73.12.130.25:8080</pipe.transport>
      <socks.mode>reverse</socks.mode>
      <socks.transport>wsn://73.12.130.25:8080/kwic</socks.transport>
      <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
    </connect-options>
    

    Replace the URLs in pipe.transport and socks.transport with a secure scheme and with the hostname you used when creating the certificate. For example:

    <connect-options>
      <tcp.bind>8443</tcp.bind>
      <pipe.transport>socks+ssl://example.com:8443</pipe.transport>
      <socks.mode>reverse</socks.mode>
      <socks.transport>wsn+ssl://example.com:8443/kwic</socks.transport>
      <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
    </connect-options>
    
  4. Add the socks.ssl.verify-client element to the proxy service connect-options. The socks.ssl.verify-client element makes the KWIC Cloud instance request a client certificate from the KWIC On-Prem instance connecting to the proxy service. (You will configure the KWIC On-Prem client certificate later.) For example:
    <connect-options>
      <tcp.bind>8443</tcp.bind>
      <pipe.transport>socks+ssl://example.com:8443</pipe.transport>
      <socks.mode>reverse</socks.mode>
      <socks.transport>wsn+ssl://example.com:8443/kwic</socks.transport>
      <socks.ssl.verify-client>required</socks.ssl.verify-client>
      <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
    </connect-options>
    
  5. On the KWIC On-Prem server, create a new self-signed client certificate for the identity (client alias) of the KWIC On-Prem server (for example, my-on-prem). This client certificate will be presented to the KWIC Cloud instance when the KWIC On-Prem server connects to it. The public key in this self-signed certificate will then be imported into the truststore on the KWIC Cloud instance.

    Each operating system has a different method for creating client certificates. If you are using the Java keytool utility, create the following components in KWIC_HOME/conf/ using keytool:

    1. A new key pair (private and public).
    2. A new certificate.
    3. The keystore that will contain the new key pair and certificate (if you do not use the default keystore).

    Here is an example of how to create these components:

    keytool -genkeypair -keystore C:\KWIC_HOME\conf\keystore.db -storetype JCEKS -storepass password -alias my-on-prem -keyalg RSA -dname "CN=example.com, OU=Example, O=Example,L=Mountain View, ST=California, C=US"

    This example command generates a key pair (public key and its associated private key) and wraps the public key into an X.509 self-signed certificate. Both the key pair and the certificate are stored in the keystore file and identified by my-on-prem (as specified by the -alias parameter).

  6. Export the public key certificate from the KWIC On-Prem server. If you are using the Java keytool utility, the command is (substitute your information for my-on-prem, client_certificate.cer, and keystore.db):

    keytool -export -alias my-on-prem -file client_certificate.cer -storetype JCEKS -keystore keystore.db

  7. Import the public key into the KWIC Cloud truststore using the Java keytool utility (substitute your information for KWIC_HOME, my-on-prem, client_certificate.cer, and changeit):

    keytool -importcert -keystore KWIC\_HOME\conf\truststore.db -storepass changeit -trustcacerts -alias my-on-prem -file client_certificate.cer

  8. On the KWIC On-Prem proxy service, update the pipe.transport and socks.transport URLs in the accept-options with a secure URL scheme and the hostname of the server running the KWIC Cloud. For example:
    <accept-options>
      <pipe.transport>socks+ssl://example.com:8443</pipe.transport>
      <socks.mode>reverse</socks.mode>
      <socks.transport>wsn+ssl://example.com:8443/kwic</socks.transport>
      <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
    </accept-options>
    

    In this example, the KWIC On-Prem server must be able to resolve the hostname example.com to the IP address of the KWIC Cloud server. If you are testing locally, you might have to add example.com to the hosts file of the KWIC On-Prem server.

  9. Add the security element to the KWIC On-Prem configuration file, KWIC_HOME/conf/kwic-config.xml. The security element identifies where the digital certificate and password file are located. For example:
    <security>
      <keystore>
        <!-- The Java keystore type -->
        <type>JCEKS</type>
        <!-- The location of the keystore file -->
        <file>KWIC_HOME/conf/keystore.db</file>
        <!-- The location of the file containing the password for the keystore -->
        <password-file>KWIC_HOME/conf/keystore-cloud.pw</password-file>
      </keystore>
      <truststore>
        <!-- The location of the truststore file -->
        <file>KWIC_HOME/conf/truststore.db</file>
      </truststore>
    </security>
    
  10. Start the KWIC Cloud server.
  11. Start the KWIC On-Prem server. The KWIC Cloud instance will provide the KWIC On-Prem instance with a server certificate. Once the KWIC On-Prem has verified that certificate, the KWIC Cloud will request a client certificate from the KWIC On-Prem. Once the KWIC Cloud has verified the KWIC On-Prem certificate, the secure connection is established.

TLS Setup for On-Prem Client to Cloud Server Configurations (Forward Connection)

The process for setting up TLS digital certificates in this scenario is the same as the reverse connection scenario described above. Once you have the certificates configured, you must make the following changes to the KWIC instances' configuration files (KWIC_HOME/conf/kwic-config.xml):

  1. On the KWIC On-Prem instance, update the proxy service connect element with a secure URL scheme and the hostname used in the server certificate of the KWIC Cloud server. For example:
    <service>
      <name>serviceB</name>
      <accept>tcp://0.0.0.0:6661</accept>
      <connect>wss://example.com:8443/serviceB</connect>
     
      <type>proxy</type>
     
      <connect-options>
        <http.maximum.redirects>3</http.maximum.redirects>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </connect-options>
    </service>
    
  2. Add the security element to the KWIC On-Prem configuration file as described in the previous section.
  3. On the KWIC Cloud instance, update the proxy service accept element with a secure URL scheme and the hostname used in the server certificate of the KWIC Cloud server, and add the ssl.verify-client element to the proxy service accept-options on the KWIC Cloud proxy service. For example:
    <service>
      <name>serviceB</name>
      <accept>wss://example.com:8443/serviceB</accept>
      <connect>tcp://localhost:6661</connect>
     
      <type>proxy</type>
     
      <accept-options>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
       <ssl.verify-client>required</ssl.verify-client>
      </accept-options>
    </service>
    
  4. Add the security element to the KWIC Cloud configuration file as described in the previous section.
  5. Start the KWIC Cloud server.
  6. Start the KWIC On-Prem server. The KWIC Cloud instance will provide the KWIC On-Prem instance with a server certificate. Once the KWIC On-Prem has verified that certificate, the KWIC Cloud will request a client certificate from the KWIC On-Prem. Once the KWIC Cloud has verified the KWIC On-Prem certificate, the secure connection is established.

KWIC 5 Cloud Clustering and Load Balancing

You can configure KWIC Cloud servers to be highly available, using clustering to protect clients and servers from hardware and software failures, and using load balancing for requests for any KWIC server. Let’s look at an example of a KWIC deployment with high availability configured:

Figure: KWIC Clustering and Load Balancing

Let's look at the key components in the example:

There is no requirement that both sides have the same number of instances. This example uses the minimum number of instances for high availability on both sides.

Notes:

Clustering KWIC Cloud 5 Servers

A KWIC Cloud cluster can be used for fault tolerance for connections coming from one or more KWIC On-Prem servers. Once you have a cluster, you can implement load balancing. For more information, see Load Balancing KWIC 5 Servers.

You configure a KWIC Cloud cluster by adding the cluster configuration element to the kwic-config.xml configuration file. In the cluster element, you add the address on which the KWIC Cloud instance is listening for other cluster members (typically, the local IP address of the KWIC server) and the cluster group address used by all cluster members to discover other cluster members. The KWIC Cloud cluster members come online, discover the other KWIC Cloud cluster members, and establish connections with their peer members.

Note: There is no concept of cluster masters and slaves; each KWIC Cloud cluster member has its own connections to clients and servers. If a KWIC Cloud cluster member terminates unexpectedly, the client or server must reconnect to the KWIC Cloud cluster.

Configuring a KWIC Cloud Cluster Member

To create a KWIC Cloud cluster, you must configure multiple KWIC Cloud servers to communicate with each other. This is accomplished by adding a cluster service to each KWIC Cloud server. Cluster members share information about activity and which of their services are load balanced.

In the following procedure, two KWIC Cloud server members are clustered. Additional members can be added or removed using the same steps.

In this example, there are two KWIC Cloud servers. Each server is listening on its IP address for incoming connections, and both are connecting to the multicast cluster group address udp://224.2.2.44:54327.

  1. On both KWIC Cloud servers, add the following cluster configuration element in the configuration file (KWIC_HOME/conf/kwic-config.xml).
    <cluster>
     <name>KWIC Cloud Cluster</name>
     <accept>tcp://@eth0:5551</accept>
     <connect>udp://224.2.2.44:54327</connect>
    </cluster>
    

    Note: The examples in this procedure use an interface alias @eth0 for the network interface name receiving the request, but you could also specify the IP address of the host running KWIC (or 0.0.0.0 for all interfaces). Using @eth0 (or the appropriate network interface name, such as tcp://[@Local Area Connection]:5551 in Windows) is portable and prevents hardcoding physical network information in the configuration. Also, @eth0 lets you easily scale by duplicating the configuration file on other other KWIC hosts without modification.

  2. Start both cluster members.
  3. When you shut down one of the instances, you should see the following message in the terminal that was used to start the remaining gateway instance: INFO Cluster member /192.168.2.10:5551 is down.

The cluster element requires name, accept, and connect elements:

Configuring KWIC On-Prem Instances to Support the KWIC Cloud Cluster

Once you set up a KWIC Cloud cluster with two members, you can configure two On-Prem KWIC servers to support connections with each KWIC Cloud cluster member.

You can configure one KWIC On-Prem instance and then copy its configuration file to a second KWIC On-Prem instance.

On the KWIC On-Prem instance, do the following:

  1. Open the KWIC On-Prem instance configuration file (KWIC_HOME/conf/kwic-config.xml).
  2. Add a proxy service for each of the proxy services in the KWIC Cloud cluster. For example, if there is a proxy service A on each of the two KWIC Cloud cluster members, then, on the On-Prem instance, add two proxy services for proxy service A, one for each KWIC Cloud cluster member.

    Let's look at an example. There is a proxy service A hosted on both KWIC Cloud cluster members:

    <service>
      <name>proxy service A</name>
    
      <accept>tcp://@eth0:5551</accept>
      <connect>pipe://serviceA</connect>
    
      <type>proxy</type>
    
      <connect-options>
        <tcp.bind>8443</tcp.bind>
        <pipe.transport>socks+ssl://example.com:8443</pipe.transport>
        <socks.mode>reverse</socks.mode>
        <socks.transport>wsn+ssl://example.com:8443/kwic</socks.transport>
        <socks.ssl.verify-client>required</socks.ssl.verify-client>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </connect-options>
    </service>
    

    On the KWIC On-Prem instance, you would add two proxy services to support connections from each of the KWIC Cloud servers: proxy service A from cloud1 and proxy service A from cloud2.

    <service>
      <name>proxy service A from cloud1</name>
    
      <accept>pipe://serviceA-cloud1.example.com</accept>
      <connect>tcp://server-a:5551</connect>
    
      <type>proxy</type>
    
      <accept-options>
        <tcp.bind>8443</tcp.bind>
        <pipe.transport>socks+ssl://cloud1.example.com:8443</pipe.transport>
        <socks.mode>reverse</socks.mode>
        <socks.transport>wsn+ssl://cloud1.example.com:8443/kwic</socks.transport>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </accept-options>
    </service>
    
    <service>
      <name>proxy service A from cloud2</name>
    
      <accept>pipe://serviceA-cloud2.example.com</accept>
      <connect>tcp://server-a:5551</connect>
    
      <type>proxy</type>
    
      <accept-options>
        <tcp.bind>8443</tcp.bind>
        <pipe.transport>socks+ssl://cloud2.example.com:8443</pipe.transport>
        <socks.mode>reverse</socks.mode>
        <socks.transport>wsn+ssl://cloud2.example.com:8443/kwic</socks.transport>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </accept-options>
    </service>
    
  3. Save the KWIC On-Prem configuration file, and then copy it.
  4. Create a new KWIC On-Prem instance and paste the configuration file into its KWIC_HOME/conf folder.
  5. Start the KWIC Cloud instances.
  6. Start the KWIC On-Prem instances.

    Now you have two KWIC On-Prem instances to support the KWIC Cloud cluster. In a KWIC On-Prem server shuts down, the remaining KWIC On-Prem server can handle connections for the KWIC Cloud cluster.

Configuring Clients and Servers to Use the Cluster

Let's take another look at the HA diagram to see the paths for clients and servers:

Figure: client and server paths

To configure clients and servers to take advantage of the KWIC Cloud cluster and the supporting KWIC On-Prem instances, do the following:

  1. For a cloud client: Ensure that the Cloud client connects to each KWIC Cloud cluster member. If one KWIC Cloud cluster member shuts down, the client can use another KWIC Cloud cluster member.
  2. For an on-prem client: Ensure that the On-Prem client connects to a proxy on each KWIC On-Prem instance. If one KWIC On-Prem instances shuts down, the client can use another KWIC On-Prem instance.
  3. For a cloud server: Ensure that each KWIC Cloud cluster member connects to the cloud server. If one KWIC Cloud cluster member shuts down, the other KWIC Cloud cluster member can connect the On-Prem client to the cloud server.
  4. For an on-prem server: Ensure that every proxy service for a cloud client connection on each KWIC On-Prem instance connects to the On-Prem server. If a KWIC Cloud cluster member shuts down and a KWIC On-Prem instance shuts down, a cloud client can still connect to the on-prem server using the remaining KWIC Cloud cluster member and the remaining KWIC On-Prem instance.

Note: Clients and servers connecting over TCP to the KWIC servers can be load balanced using a TCP load balancer.

Load Balancing KWIC 5 Servers

Load balancing is used to balance connection loads from KWIC On-Prem servers to a cluster of KWIC Cloud servers. KWIC's load balancing feature, using its balancer service, is used solely for KWIC forward connections:

server <- KWIC Cloud cluster <- web <- KWIC On-Prem <- client

For more information, see Configuring a KWIC Cloud Cluster Member and On-Prem Clients Connecting to Cloud Servers.

When an on-prem client connects to a cloud server over KWIC, the KWIC Cloud cluster members configured to load balance on-prem client connections determine which KWIC Cloud cluster member should manage the connection to the cloud server.

Notes:

To configure load balancing, you configure each KWIC Cloud cluster member with a balancer service. The balancer service has accept elements for each KWIC On-Prem connection that will be balanced across the cluster. Each cluster member configured with a balancer service acts as a load balancer for all members.

Next, in the proxy service elements on each KWIC Cloud server, you add balance child elements containing the same URIs you configured in the balancer service.

To Load Balance KWIC Cloud Servers

  1. Configure a balancer service in each KWIC Cloud server that will participate in load balancing (each cluster member). The balancer service has an accept for each URI that will be balanced across participating KWIC Cloud servers. The URI in the accept of the balancer service is the URI that KWIC On-Prem servers use when connecting to the cluster for the first time. For example, the following KWIC On-Prem instance has a proxy service named proxy service B with a connect URI that connects to the KWIC Cloud cluster:
    <service>
      <name>proxy service B</name>
    
      <accept>tcp://@eth0:6661</accept>
      <connect>wsn+ssl://example.com:8443/serviceB</connect>
    
      <type>proxy</type>
    
      <connect-options>
        <http.maximum.redirects>3</http.maximum.redirects>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </connect-options>
    </service>
    

    In each of the KWIC Cloud cluster members, add the balancer service to balance connections to <connect>wsn+ssl://example.com:443/serviceB</connect>:

    <service>
      <name>balancer service B</name>
    
      <accept>wsn+ssl://example.com:8443/serviceB</accept>
    
      <type>balancer</type>
    
      <accept-options>
        <tcp.bind>8443</tcp.bind>
      </accept-options>
    </service>
    

    For production environments, the hostname in the accept element must resolve in DNS to the IP addresses of every cluster member. Multiple DNS A resource records should be registered for the hostname in the accept URI, with each A record mapping the hostname to the IP address of one cluster member. To register these DNS records, you will need access to the public DNS zone for the hostname, or the assistance of your network administrator or Internet Service Provider (ISP). All ISPs provide ways for their customers to update their DNS zones with new hostnames and IP addresses.

  2. Configure the forward connection proxy service of each KWIC Cloud cluster member with a balance element for each URI accepted by the balancer service. KWIC On-Prem servers will use these URIs to connect to the proxy service.
    <service>
      <name>proxy service B</name>
    
      <accept>wsn+ssl://example.com:8443/serviceB</accept>
      <connect>tcp://server-b:6661</connect>
      
      <balance>wsn+ssl://example.com:8443/serviceB</balance>
    
      <type>proxy</type>
    
      <accept-options>
        <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
      </accept-options>
    </service>
    

    The balance and accept element URIs in a proxy service must use the same port number and path. The hostnames in the URIs may be different.

  3. Ensure that each KWIC Cloud server participating in load balancing is configured with a cluster service, as described in Configuring a KWIC Cloud Cluster Member.
  4. Start all cluster members.

KWIC 5 Logging and Troubleshooting

KWIC 5 logging is performed using Apache Log4j. The Log4j settings file is located in KWIC_HOME/conf/log4j-config.xml. The error log is located in KWIC_HOME/log/kwic.log.

Possible Issues

This section lists common errors can occur when you are setting up KWIC 5.

Unable to resolve DNS name: server_name

This most often occurs when the a server name is used in the proxy settings but KWIC cannot resolve the name to an IP address using DNS. For development purposes, simply add the server name and IP to the hosts file of the KWIC server. For production deployment, ensure that any name that is used in the proxy server can be resolved using DNS.

KWIC instances are not connecting

Ensure that the names in the pipe:// addresses in both the Cloud and KWIC On-Prem instances are the same. For more information, see Cloud Client to On-Prem Server Configurations (Reverse Connection).

Another reason why KWIC instances might not connect is because a firewall will not allow the port used in the KWIC connection. For example, a KWIC On-Prem instance is configured to connect to a KWIC Cloud instance over the location 73.12.130.25:8080 but the firewall in front of the KWIC Cloud instance does not allow traffic over port 8080.

To resolve this issue, configure the firewall to allow port 8080. For example, you can set up port forwarding for 8080 on your router's firewall. Here is information on how to perform port forwarding on a common ISP router: What is Port Forwarding on the XFINITY Wireless Gateway?

When the KWIC connection is established, the terminal output by both the KWIC instances will indicate the connection is working. When the KWIC On-Prem instance connects to the KWIC Cloud instance, you will see output indicating the connection. For example:

DEBUG Reverse connection ready: pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:58167
DEBUG Proxy accepted for "serviceA": accept=[pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:58167, remote=73.12.130.25:8080], connect=[tcp://localhost:5552, local=127.0.0.1:58171, remote=127.0.0.1:5552]

On the KWIC Cloud instance, you will see corresponding information that shows that the KWIC connection is running. For example:

DEBUG Reverse connection ready: pipe://servicea via wsn://73.12.130.25:8080/kwic, remote=12.203.64.50:2409
DEBUG Proxy accepted for "serviceA": accept=[tcp://0.0.0.0:5551, local=127.0.0.1:5551, remote=127.0.0.1:53364], connect=[pipe://servicea via wsn://73.12.130.25:8080/kwic, local=127.0.0.1:8080, remote=12.203.64.50:2409]

Possible Intermediary WebSocket Issue

In some instances, the KWIC connection might pass through an older proxy server that does not support WebSocket. To determine if this is an issue, open a browser on each of the connection points, and browse to websocketstest.com. The best solution to this problem is to configure the KWIC connection to use TLS as described in Production KWIC 5 and Security.

Network proxy uses a version of TLS different than the KWIC default

The default version of TLS used by KWIC is TLSv1. If you need KWIC to use a different version of TLS to support a network proxy using a different version of TLS, use the socks.ssl.protocols element in connect-options of one KWIC proxy and the ssl.protocols element in the accept-options of the other KWIC proxy, depending on which direction the client-to-server connection over KWIC is traveling. For example:

...
 <connect-options>
   <pipe.transport>socks://example.com</pipe.transport>
   <socks.mode>reverse</socks.mode>
   <socks.transport>wsn+ssl://example.com/kwic</socks.transport>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
   <socks.ssl.verify-client>required</socks.ssl.verify-client>
   <socks.ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</socks.ssl.protocols>
 </connect-options>
...
 <accept-options>
   <ws.inactivity.timeout>55 seconds</ws.inactivity.timeout>
   <ssl.verify-client>required</ssl.verify-client>
   <ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</ssl.protocols>
 </accept-options>
...

KWIC Reconnections

If the KWIC connection is lost, the KWIC On-Prem instance attempts to reconnect with the KWIC Cloud instance. The KWIC Cloud and On-Prem instances report lost and re-established connection information in the terminal that you can use to diagnose networking issues.

For example, if the KWIC On-Prem instance is shutdown, the KWIC Cloud instance will report the closed connection as follows:

DEBUG Reverse connection closed: pipe://servicea via ws://73.12.130.25:8080/kwic, remote=12.203.64.50:4919

Note the IP address and port in the remote tag. It indicates the public IP address of the KWIC On-Prem server and ephemeral port number from which the KWIC Cloud instance is receiving the On-Prem instance connection. The private IP address on the KWIC On-Prem server is not received by the KWIC Cloud instance, nor is it ever broadcast over the connection.

When the KWIC On-Prem instance is restarted, it will reconnect with the KWIC Cloud instance. The KWIC Cloud instance reports the re-established connection:

DEBUG Reverse connection ready: pipe://servicea via wsn://73.12.130.25:8080/kwic, remote=12.203.64.50:3066

If the KWIC Cloud instance is shutdown, the KWIC On-Prem instance will report the lost connection:

DEBUG Reverse connection closed: pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:59299

Note the IP address and port in the local tag. This IP address and ephemeral port number is different from the public address used in the proxy service configuration, ws://73.12.130.25:8080. The local tag indicates the local IP address of the KWIC On-Prem server. It is only reported to the KWIC On-Prem instance and never sent over the Internet.

The KWIC On-Prem continues to attempt to connect with the the KWIC Cloud instance. When the KWIC Cloud instance is restarted, the KWIC On-Prem reports the re-established connection:

DEBUG Reverse connection ready: pipe://servicea via ws://73.12.130.25:8080/kwic, local=192.168.5.193:59298

Note: To see the KWIC instances report lost and re-established connections in the terminal, you need to have the terminal window active (selected).

Update Check

The Update Check feature checks to see if there are new versions of KWIC available when the KWIC instance is started. New versions include patches, and minor and major releases. Update Check is enabled by default.

The update check output information is displayed in the log file (KWIC_HOME/log/kwic.log), the terminal or command prompt screen.

KWIC will start regardless of whether the update check is successful. If the update check fails, then a warning is logged to the log file and terminal or command prompt screen.

If you do not want KWIC to check for updates, stop the KWIC instance and then configure KWIC using the following GATEWAY_OPTS environment variable:

GATEWAY_OPTS=-Dcom.kaazing.server.UPDATE_CHECK=false

Windows Example:

> SET GATEWAY_OPTS=-Dcom.kaazing.server.UPDATE_CHECK=false

Mac Example:

$ export GATEWAY_OPTS=-Dcom.kaazing.server.UPDATE_CHECK=false

Next, start the KWIC instance.