---
title: "Installing and using the Key9 Proxy Service for Linux"
slug: "installing-and-using-the-key9-proxy-server-for-linux"
updated: 2025-07-28T15:46:14Z
published: 2025-07-28T15:46:14Z
canonical: "docs.telosalliance.com/installing-and-using-the-key9-proxy-server-for-linux"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telosalliance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [!WARNING]
> If you need a Windows version, please see our [Installing and using the Key9 Proxy server for Windows document](/v1/docs/installing-and-using-the-key9-proxy-server-for-windows).

## 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.

![](https://cdn.document360.io/57e3cd80-d493-453c-9672-ad1b043dadc3/Images/Documentation/12a77f2d-cae6-4c3b-ba0b-26d1ab354c66-image.png)

## 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:

```plaintext
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](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#removal-of-key9-proxy-service)” steps Example of running key9proxy service:

```plaintext
● 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](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#removal-of-key9-proxy-service)” steps Example of stopped key9proxy service:

```plaintext
○ 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**](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#download-key9-proxy-application)**”** Example of non existing key9proxy service:

```plaintext
● 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:

```plaintext
sudo systemctl stop key9proxy.service
```

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

```plaintext
sudo systemctl disable key9proxy.service
```

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

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

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

```plaintext
sudo systemctl daemon-reload
```

Service is now removed, proceed to next section

### Download Key9 Proxy Application

1. Access the Linux terminal either remotely via SSH or locally with a connected keyboard and monitor.
2. 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:

```plaintext
cd ~
```
3. The current version of the Key9 Proxy application can be downloaded by running this command:

```plaintext
wget https://telos-public.s3.amazonaws.com/downloads/telos/Key9Proxy/linux/key9proxy2.0.1
```
4. Set the file to be executable by running this command:

```plaintext
 $ 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:

```plaintext
./key9proxy2.0.1 --config
```

#### Configuration step by step

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

```plaintext
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

```plaintext
Key9 listen interface and port [0.0.0.0:42131]:
```

> [!NOTE]
> 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`

> [!NOTE]
> The https address[https://secure2.telos-systems.com](https://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

```plaintext
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

```plaintext
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

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

> [!WARNING]
> 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

```plaintext
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:

```plaintext
$ ./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:

```plaintext
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](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#troubleshooting)

### 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:**

```plaintext
sudo ./key9proxy2.0.1 --install
```

Example terminal output after installing:

```plaintext
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](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#troubleshooting)

**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:

```plaintext
sudo ./key9proxy2.0.1 --start
```

Example terminal output after starting:

```plaintext
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](/v1/docs/installing-and-using-the-key9-proxy-server-for-linux#troubleshooting)

### 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](http://10.0.55.33:8080)

**2) Accept the EULA Agreement:**

![](https://cdn.document360.io/57e3cd80-d493-453c-9672-ad1b043dadc3/Images/Documentation/image-XW7FKEYF.png)

**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

![](https://cdn.document360.io/57e3cd80-d493-453c-9672-ad1b043dadc3/Images/Documentation/image-CTLLFYLF.png)

**4) Login with the new credentials that you set:**

![](https://cdn.document360.io/57e3cd80-d493-453c-9672-ad1b043dadc3/Images/Documentation/image-SQZH2DK6.png)

**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

![](https://cdn.document360.io/57e3cd80-d493-453c-9672-ad1b043dadc3/Images/Documentation/image-IIPFACGS.png)

- **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](http://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](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