Installing and using the Key9 Proxy server for Windows

Updated by Bryan Jones

Scope

This document covers the setup of the Telos Alliance Key9 License Server Proxy for Windows on a computer in your facility. Many Telos products require this for licensing; however, no individual product support is covered in this document.

If you need a Linux version, please see our Installing and using the Key9 Proxy server for Linux document.

Description

Some Telos Alliance products require a license to operate. These licenses activate (or deactivate) features allowing flexibility in your operating model and allowing for software updates, priority support, etc. These licenses are controlled by a cloud-located activation server, meaning your products must have access to this server.

Often the networks to which these products are connected are purposely not connected to the internet. For this reason, Telos Alliance offers this proxy server which can reside on a computer that DOES have access to the internet.

Here's a diagram of a typical configuration.

Configuration

  1. Click here to download the Key9 Proxy (version 2.0.1a) and save it to a folder with read/write permissions.
    The location of the key9proxy executable will be the location it will run from, even as a service. Please make sure you save the file to a central location like C:\key9proxy\ , avoid saving under a user profile folder like My Documents
  2. Open a command prompt with Administrative rights and navigate to the location of key9proxy
You may need to right-click on your command prompt icon and choose Run as administrator. Administrative privileges are required to install the proxy as a service.
  1. Create a configuration file. From the command prompt run
    >win-key9proxyV2.0.1a.exe --config
    You must type YES to agree to the EULA (End User License Agreement) and press Enter to continue.
    1. Specify the Listen Interface and port. The default is [0.0.0.0:42131] which means the proxy will listen for license requests on any network interface. If the default is acceptable press Enter
    2. Specify the Remote server address. This is the address of the key9 Cloud license server
      You may use either:
      secure2.telos-systems.com:42131
      https://secure2.telos-systems.com (preferred)
    3. Specify the HTTP Server (the web gui of the proxy) Listen Interface and port. The default is [127.0.0.1:8080] which means the HTTP server will only allow you to access the web gui from the same Windows host that is running the proxy on TCP port 8080. You could change this to 0.0.0.0:8080 to allow the HTTP server to be reachable via all interfaces on the server. We do that in the example below
    4. Specify the Windows account to run the service under. We recommend leaving this blank to use the default Windows service account
  2. The key9 Proxy configuration is now complete
  3. Run the proxy in test mode first
>win-key9proxyV2.0.1a.exe

You should see similar terminal output

  1. Attempt to connect to the web gui of the Key9 Proxy

In my example below. I have opened the web browser on the same Windows host that is running the Key9 Proxy in test mode from step 5

If you set the web server to listen to any interface [0.0.0.0:8080] or a specific network interface . You can attempt to open up a browser on a PC that can access that network. Instead of 127.0.0.1 as the IP, change this to match the IP of the network interface on the Key9 Proxy server

  1. Accept the EULA agreement once more from the product web gui and click Continue
  2. Set the username and password for the web gui
    You should then get a message that credentials have been saved, Click OK
  3. Test that you can login with your credentials
  1. Stop running Key9 Proxy in Test mode
    Press CTRL + C in the command prompt window to stop it
  2. Install Key9Proxy as a Windows Service
    >win-key9proxyV2.0.1a.exe --install
  3. Start the Key9 Proxy service. It will automatically start the next time Windows is restarted
    >win-key9proxyV2.0.1a.exe --start

Notes

After the proxy server is installed, configured, and tested, you will need to configure all Telos alliance products to point to the proxy server instead of the cloud license server.

The product configuration depends on the product. VXs does this through an unlinked web page.

If you modify the configuration file, you will need to restart the service before the new options will take effect.

When configuring the service, you may leave the username as blank.

It is safe to briefly take the proxy server down even if the products use it. The license refresh mechanism will retry later.

key9proxy.exe offers additional command line options. Executing the program without arguments will display help texts with the available options.

Troubleshooting

If the Key9Proxy Service can't reach the Key9 Cloud server, it will not be able to handle license requests from the Telos Products that use it.

Using Key9Test tool

You can use the Key9Test tool to verify connectivity with the Key9 Cloud Server. As well, you can use the tool to connect to the Key9Proxy server to confirm that the Key9Proxy server handle communicate with the Key9 Cloud Server. You may also run this tool on a different Windows host to simulate a Telos Product running on the network, trying to communicate with the Key9Proxy for licensing requests

Click Here to Download Key9Test Tool for Windows (x86) (v1.0.1)

Click Here to Download Key9Test Tool for Linux (x86) (v1.0.1)

Testing Key9 Cloud Server connectivity:

Check that the Windows Host can make a connection the key9 cloud license server

Please note this is essentially testing the resolved address of secure2.telos-systems.com:42131

>key9test.exe --cloud

Getting OK as response, confirms that the Key9 Cloud server is reachable from the Windows host it was run on

Testing Key9 Proxy Server connectivity:

Check that a Telos product can make a connection to the Key 9 Proxy Server, and that the Key 9 Proxy relays and gets a response from Key 9 Cloud Server. This is a good "end to end" test

If you are running key9test on the same host that key9 proxy server is running on, you can run key9test like this:

>key9test.exe 127.0.0.1:42131

If you are running key9test on a different host, simply point it to the IP address of the key9 proxy server. Just like if this were a Telos product, that was configured to communicate to the Key 9 Proxy Server IP. Here is an example:

>key9test.exe 10.0.1.113:42131

Getting OK as response, confirms that Key9 Proxy Server is reachable over your local network. Additionally, the OK response means that the Key9 Proxy Server got a response back from the Key 9 Cloud server (using the Remote Server address you configured in Step 3.B)

Network Firewall/Router

When a firewall is present, the only requirement is to allow outbound TCP connections to secure2.telos-systems.com:42131

If using the https cloud server, then allowing HTTPS connections established to https://secure2.telos-systems.com

There is no need to open incoming ports since the products and the proxy always reach outward to the license server. The license server will never make an inbound connection. While most firewalls allow outgoing connections by default, for some customers, this has to be explicitly allowed.

Windows Firewall

Windows Firewall, or any additional software firewall on the Windows host will need to allow inbound TCP connections on port 42131. These are local connections being made from the Telos Products to the Key9 Proxy Server host

This can be as simple as adding the Key9Proxy executable to Allowed Apps in Windows Defender Firewall

How did we do?