Installing and using the Key9 Proxy Service for Linux

Scope

This document covers the setup of the Telos Alliance Key9 Proxy Service for Linux on a server/VM in your facility

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

Description

Some Telos Alliance products require a license to operate. These licenses activate (or deactivate) features in the product allowing software updates, priority support, etc. These licenses are controlled by a Cloud hosted activation server. This means that your products must have access to this server. By default these Telos Alliance products will send their activation requests directly to our Cloud hosted activation server.

Many of the networks these products connect to are intentionally kept offline for security reasons. To support this, Telos Alliance provides the Key9 Proxy Service. This service runs on a physical server or virtual machine that does have internet access as well as access to the isolated production network. The Key9 Proxy acts as a bridge, handling activation requests from local devices and securely forwarding them to the cloud-based activation server. This setup allows production equipment to stay offline while still completing activation through the proxy.

Here's a diagram of a typical configuration.

Prerequisites

Acceptable Linux Distros are: ~~Ubuntu Server 20.04~~ (now EOL), Ubuntu Server 22.04, Ubuntu Server 24.04
Must have access to a network that allows either, outbound https connections or outbound TCP connections on port 42131 (to be able to contact the cloud license server)
Must have access to the production network that the Telos Alliance products exist on

Configuration and Installation

Uninstall any previous version

If you have previously installed Key9 Proxy Service on the same system, you need to stop it and uninstall it to prevent any conflicts.

If this is a new install, skip this section and move onto the next section

Check if Key9 Proxy Service already exists

Execute the following command to check if Key9 Proxy already exists as a service:

sudo systemctl status key9proxy.service

🛑If it shows that the service is ‘active (running)’ then the service must be stopped and then uninstalled. Stop and follow “Removal of Key9 Proxy Service” steps
Example of running key9proxy service:

● key9proxy.service - This is a proxy service for the Telos Alliance key9 license server
     Loaded: loaded (/etc/systemd/system/key9proxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2025-07-25 16:19:31 UTC; 14min ago
   Main PID: 647 (key9proxy)
      Tasks: 8 (limit: 4557)
     Memory: 13.0M
        CPU: 688ms
     CGroup: /system.slice/key9proxy.service
             └─647 /home/brett/key9proxy

🛑If it shows that the service is ‘inactive (dead)’ then the service is already stopped but still needs to be uninstalled. Stop and follow “Removal of Key9 Proxy Service” steps
Example of stopped key9proxy service:

○ key9proxy.service - This is a proxy service for the Telos Alliance key9 license server
     Loaded: loaded (/etc/systemd/system/key9proxy.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Fri 2025-07-25 16:34:34 UTC; 8min ago
   Main PID: 647 (code=exited, status=0/SUCCESS)
        CPU: 728ms

✅If it show that the service is ‘not-found’ , then the service doesn’t exist — Proceed to the next section “Download Key9 Proxy Application”
Example of non existing key9proxy service:

● key9proxy.service
     Loaded: not-found (Reason: Unit key9proxy.service not found.)
     Active: active (running) since Fri 2025-07-25 16:50:33 UTC; 7min ago
   Main PID: 56620 (key9proxy)
        CPU: 424ms
     CGroup: /system.slice/key9proxy.service
             └─56620 /home/brett/key9proxy

Removal of Key9 Proxy Service

1) Stop the Key9 Proxy service, run the following command:

sudo systemctl stop key9proxy.service

2) Disable the Key9 Proxy service, run the following command:

sudo systemctl disable key9proxy.service

3) Remove the Key9 Proxy Service file, run the following command:

sudo rm /etc/systemd/system/key9proxy.service

4) Reload service files to complete the removal, run the following command:

sudo systemctl daemon-reload

Service is now removed, proceed to next section

Download Key9 Proxy Application

Access the Linux terminal either remotely via SSH or locally with a connected keyboard and monitor.
For most users, the Key9 Proxy application will exist in the “home” directory of the current user. To ensure you are in the home directory run this command:
```
cd ~
```
The current version of the Key9 Proxy application can be downloaded by running this command:
```
wget https://telos-public.s3.amazonaws.com/downloads/telos/Key9Proxy/linux/key9proxy2.0.1
```
Set the file to be executable by running this command:
```
 $ chmod +x key9proxy2.0.1
```

Proceed to next section

Configure Key9 Proxy Application

Before the Key9 Proxy Application can be installed, we must first set the configuration by running this command:

./key9proxy2.0.1 --config

Configuration step by step

1) After reviewing the EULA, type YES and press enter

Please type YES to agree to the EULA and continue: YES

2) By default, the Key9 Proxy will listen for incoming license requests on all interfaces via TCP port 42131.
Don’t enter anything here, just press enter

Key9 listen interface and port [0.0.0.0:42131]:

Optional
If you want to restrict which interface the Key9 Proxy will only use for incoming license requests, enter the IP of the network interface followed by the port number. I.E 10.0.5.22:42131
Unless required, still use 42131 as the port number

3) The Remote Server address must be set. This is the address to the Cloud Key9 Server
You can use either secure2.telos-systems.com:42131 or https://secure2.telos-systems.com

The https addresshttps://secure2.telos-systems.com) may be favorable to use if your router/firewall blocks outbound TCP connections to port 42131

Enter in the desired Key9 Cloud server address and press enter

Remote server address []: https://secure2.telos-systems.com

4) The Key9 Proxy Service provides a web ui. This is used to complete the configuration and for further management of the service.

By default the web ui will only be accessible from the same host that is running the key9proxy service on http port 8080
For most customers it is desirable to be able to reach the web ui from other PC’s on the network.

To allow the web ui to be reachable from a single network interface:
Enter in the IP address of the network interface, followed by a colon and the desired http port number. If you wish to use the default http port, then use :80

HTTP server address and port [127.0.0.1:8080]: 10.0.1.132:8080

To allow the web ui to be reachable from all network interfaces:
Enter in 0.0.0.0 as the IP, followed by a colon and the desired http port number. If you wish to use the default http port, then use :80 (ensure no other

HTTP server address and port [127.0.0.1:8080]: 0.0.0.0:8080

Ensure that the port number specified isn’t already being used by another application
For example, you run Telos VXs in host network mode on the same host as Key9 Proxy. VXs web ui will use port 80. In that case, the key9 proxy application can NOT use port 80 for its web ui, use a different port number

5) Key9 Proxy Service can be run under a specific user account
This setting is not required for most customers. Unless you need this, do not enter anything here and press enter

Run service as user []:

6) This completes the terminal based configuration

Please proceed to the next section to test the Key9 Proxy Service

Test Key9 Proxy Application Configuration

Before installing the Key9 Proxy Application as a service, it is a good idea to test it.

When running Key9 Proxy in test mode, you can check the following:

Can the Key9 Proxy reach the Key9 Cloud License Server?
Are you able to reach the web ui of Key9 Proxy?
Can the Telos Alliance container product(s) reach the Key9 Proxy?

Start the Key9 Proxy Application in test mode by running this command:

$ ./key9proxy2.0.1 --test

Can the Key9 Proxy is able to reach the Key9 Cloud License Server?
In the terminal output look for: Test connection to https://secure2.telos-systems.com: ok
If this shows as OK, this means that the Key9 Proxy is able to reach the Key9 Cloud License server.

Are you able to reach the web ui?
Try to access the web ui from a computer on the same network(s) that you allowed in the Key9 Proxy http config
It should display a page prompting you to accept the EULA. For now, don’t proceed forward. Just confirm that the page does load

Can the Telos Alliance container product(s) reach the Key9 Proxy?
This step will require you to change the license server address used in the Telos Alliance product. The steps required to make that change will vary with the product.
Most of the time the License Servers list can be changed on the License page in the product’s web ui. If unsure, consult the production documentation or reach out to Telos Alliance Support

After changing the license server address in the product. On the product’s License page, click the Activate button to force an activation request.
In the Linux terminal, where you started the Key9 Proxy in test mode. You should see a similar log line appear after making the activation request:
2025/07/25 22:14:48 Received reply from 'https://secure2.telos-systems.com' This confirms the Key9 Proxy received the activation request, sent it to the cloud server, and received the reply back
In the Telos Alliance product, the license page should indicate a positive feature count and no error message about contacting the license server

Example terminal output after running in test mode:

Telos Alliance License Server Proxy v2.0.1. Copyright (C) 2023 TLS Corp.
-------------------------------------------------------------------------

I: 22:13:42 Started on linux-systemd
2025/07/25 22:13:42 Proxy: Add HTTP/HTTPS target server: https://secure2.telos-systems.com
2025/07/25 22:13:42
-------------------------------------------------------------------------
Test connection to https://secure2.telos-systems.com: ok
-------------------------------------------------------------------------
2025/07/25 22:13:42 Starting HTTP server on  0.0.0.0:8080
2025/07/25 22:13:42 Proxy: Add HTTP/HTTPS target server: https://secure2.telos-systems.com
2025/07/25 22:13:42 Proxy: listening for product requests on 0.0.0.0:42131
2025/07/25 22:13:57 Alive 1: 0 requests, 0 read errors, 0 send errors
2025/07/25 22:14:12 Alive 2: 0 requests, 0 read errors, 0 send errors
2025/07/25 22:14:48 Received reply from 'https://secure2.telos-systems.com'

Use CRTL + C to stop running the Key9 Proxy in test mode

If everything works correctly, proceed to the next section. If you ran into issue, please scroll down to the Troubleshooting section

Install Key9 Proxy Application as Service

The install process will add Key9 Proxy as a Linux service. This way, the Key9 Proxy Service will run automatically during startup of the Linux OS

1) Install the Key9 Proxy Application as a service, run this command:

sudo ./key9proxy2.0.1 --install

Example terminal output after installing:

Telos Alliance License Server Proxy v2.0.1. Copyright (C) 2023 TLS Corp.
-------------------------------------------------------------------------

2025/07/25 22:53:45 Service key9proxy has been installed, but is not yet started

If you do not see a similar output, please scroll down to the Troubleshooting section

2) Lastly, you will need to manually start the service. The Key9 Proxy Service will run automatically on boot after this point forward

To start the Key9 Proxy Service, run this command:

sudo ./key9proxy2.0.1 --start

Example terminal output after starting:

Telos Alliance License Server Proxy v2.0.1. Copyright (C) 2023 TLS Corp.
-------------------------------------------------------------------------

2025/07/25 22:57:55 Service key9proxy has been started

If you do not see a similar output, please scroll down to the Troubleshooting section

Access Key9 Proxy Web GUI

The last step of the installation is to Accept the EULA and set the web ui username/ password

1) Open a Browser and put in the IP:Port address of the Key9 Proxy web ui.

Ex. http://10.0.55.33:8080

2) Accept the EULA Agreement:

3) Set desired username and password for web gui login:

Note, setting a password is optional. Most will want a password set, but those that do not want to set a password and simply set the username and click Save Credentials

4) Login with the new credentials that you set:

Key9 Proxy Service is now installed and operational.

All configuration steps are now complete.

You may begin to start point the Telos Alliance products to use the Key9 Proxy Service

Additional Remarks

After the proxy server is installed, configured, and tested, you 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.
For example, VXs does this through an unlinked web page. Products like PDMX and Forza allow you to change this from the License Page in the product web gui. Products like Altus or Zephyr Connect require that the product be stopped and the “license.json” file be modified to point to the correct server. Please reach out to Telos Support if unsure
If you need to change the configuration of , you must restart the service before the new options take effect.
It is safe to briefly take the proxy server down even if the products use it. The license refresh mechanism will retry later.
You can run multiple instances of the Key9 Proxy Services on different servers/VM’s. All Telos Alliance products allow the use of multiple License Server addresses that it will attempt to use. This allows you to have redundant Key9 Proxy Services available to the Telos Alliance products
Key9 Proxy Application offers additional command line options. Executing the program without arguments will display help texts with the available options.

Key9 Proxy Web GUI overview

The web GUI provides basic administration of the Proxy service

System - The main page you see after logging in. It just provides links to the Products and Settings pages
Products - Some Telos Alliance products have the ability to report back their status to the Key9 Proxy Service. Not all Telos Alliance products have this ability. Products that are able to report their status back will appear on the Products page and on the Products Dashboard page. If you do not see your products showing here, that does NOT mean the product is not able to reach the Key9 Proxy Service. It only means that the product either isn’t able to send Reports, isn’t configured to send Reports or isn’t configured to send Reports to the Key9 Proxy Service IP:Port
Settings - Allows the user to set a syslog server IP, change the address used to contact the Key9 Cloud License Server, and change the Username and Password of the web gui
Logout - Logs the user out of the Key9 Proxy Web GUI

Troubleshooting

I can’t download the Key9 Proxy Server application

Ensure that the server does have internet access and working DNS. A simple ping test to google.com should indicate responses

Ensure that the “wget” application is installed on the Linux OS. On Ubuntu Server, wget can be installed with the command sudo apt install wget

In test mode, it does not say OK for the test connection to the Key9 Cloud Server

Determine which address you used in Key9 Proxy for the Cloud License server

If you used secure2.telos-systems.com:42131 — ensure that the Linux Server can resolve DNS. A simple ping test to secure2.telos-systems.com should resolve to the public IP address it is behind. If this fails to resolve, ensure that you have working DNS first. If this resolves to the public IP without issue, then make sure that this Linux Server is able to make outbound TCP connections on port 42131

If outbound TCP connections on port 42131 are blocked by your organizations firewall. Instead, try using https://secure2.telos-systems.com as that will use HTTPS over 443

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

In test mode I can’t reach the web ui

When configuring the Key9 Proxy Service, did you allow either a specific NIC or any interfaces (0.0.0.0)? If you left it at the default (127.0.0.1), the web gui won’t be accessible from different PC’s
- Re-run the configuration and check the HTTP settings

When configuring the Key9 Proxy Service, did you set a specific port? Are you using that port in the address put into the browser (Ex http://10.0.5.22:8080) ?
- Re-run the configuration and check the HTTP settings

Does the PC you are using to reach the Key9 Proxy Web gui have connectivity to the network(s) that Key9 Proxy Web gui is allowed to use?
- Check the network config on the Linux system running the Key9 Proxy. Check the network config on the PC you are trying to reach the Key9 Proxy Web gui. Are they on the same network? Can you ping the Key9 Proxy Server’s IP address from this other PC?

In test mode my product shows an error that it can not contact license server

Ensure that the product itself can reach the Key9 Proxy Service.
Ensure that you have the correct License Server IP:Port in place in the Telos Product. Remove the license server entry that points to the Cloud Server if it still exists
When you configured the Key9 Proxy Service, ensure that the correct interface IP was entered. Make sure that the Telos Product is able to reach Key9 Proxy Service over that network. If not sure, re-run the configuration and set the “Key9 listen interface and port” to 0.0.0.0:42131
If possible, in the Telos Product (from the host OS it runs on) Use a telnet client like PuTTY to find out if a TCP connection can be established to the proxy server. You must change the Port that the telnet client uses to match the TCP port that the Key9 Proxy Server was configured to use. Unless this was purposely changed, it should be port 42131

In test mode when I try to activate a license from the product’s web gui, I get an error

See advice from “In test mode my product shows an error that it can not contact license server” above

During install steps, I get an error

Make sure that you are putting sudo in front of the command to install and start the service