User Guide: 3CX Relay for Linux


The VoIPTools Relay makes it possible for applications to communicate with the 3CX Call Control API (running on the 3CX server) from anywhere on the internal network or over the public internet.


Linux Console Access

You will need root access to your Linux console to run the setup program. You will need your 3CX server IP address, an administrative user (root), and a password.


You will need a remote access program such as Putty to issue Linux commands.


To enable our tools to remotely communicate with the relay, you will need to open (port forward) TCP 8800 on your firewall, pointing to the 3CX server. If you use the built-in Linux firewall (iptables), the setup program will attempt to open port 8800 for you. If you use a different firewall or select a different port, you will need to configure your firewall to provide remote access to the Relay.

3.Installing the 3CX Relay for Linux (Debian)

The only application you install directly on the 3CX server is the Relay.  The Relay makes it possible for our tools to communicate with the 3CX Call Control API.   The remainder of our tools are always installed on a separate Windows server.

i). Download and run the setup program

Once you have installed 3CX and have access to the Linux console, you can download the Relay setup program directly to your Linux server. There are essentially 3 steps to install the Relay:

If you are upgrading, be sure to look at the steps in Upgrade Relay section before continuing.

1. Download the setup program with the following command

sudo wget

Figure 1: Download Setup Program

— Wait until the setup program downloads successfully.

Figure 2: Setup Program Downloaded Successfully

2. Give execute permissions to the setup program by entering this command

sudo chmod +x setup

Figure 3: Give Execute Permissions to Setup Program

3. Execute the setup program with the following command

sudo ./setup

Figure 4: Execute Setup Program

When the installation is complete, the setup program will display a message with the URL needed to access the web-based Relay administration console. Your URL should be something similar to the following:


Replace <3cx-server-ip> with the IP address of your 3CX server, or FQDN.

Figure 5: URL for Accessing Web-Based Relay Administration Console

ii). Register your license key

If you previously registered your Relay, the existing licensing information will be preserved. For new installs, select the licensing option from the left-side panel. Enter your license information and press the “Register” button. If you do not have a license key, you can still use our free tools. To access the Relay API, you must register with a valid license key.

When registering your license key, the contact information should be the end-user (customer).  Be sure to include the Reseller company name if purchased through a 3CX Reseller. When complete, press the “Register” button to activate your license key. Note: It is not necessary to restart the Relay after registering your key.

Figure 6: Register License

iii). Services

The Relay can be configured to respond to an IP address or FQDN (or both), and you can change the default port used (not recommended). Typically the default settings are sufficient, but you can use the “Server Bindings” field to define the URLs accepted by the Relay/REST API.  You can enter multiple URLs separated by a space.  For example:

To change these settings, select “Services” from the left-hand side panel. After making changes to either the server bindings or port, it is necessary to restart the Relay. You can restart the relay by pressing the “Restart” button. Note: Restarting the Relay during production hours will temporarily stop the sending of events to client applications. Use wisdom when choosing a time to restart the Relay.

Figure 7: Services

4.Upgrade Relay

Upgrading the relay is as simple as running the setup program again (see the section above). The setup program deletes the existing Relay (while preserving any settings) and downloads and installs the latest Relay. However, there are a few details to consider.

If you have downloaded the setup program previously, you will want to delete the old setup program. To see if a previous version is already downloaded, login to your Linux console and run the following command:

ls setup

Figure 8: Check if previous version already exists

This command displays a list of existing files at your current location on disk.

To delete a previous version of the setup program, run this command

rm setup

Figure 9: Delete previous version of setup program

When updating the relay, the setup program will display a warning message explaining that the previous version of the Relay and logs will be deleted. Press “y” to confirm:

Continue? [y/n] : y

Figure 10: Press ‘y’ to delete previous Relay and logs

After pressing ‘y’ the setup program will immediately begin the setup process. It will capture your existing Relay settings, remove the existing Relay, download and install the latest available relay, and restore your previous settings.

You can configure the Relay to check for updates daily. Enter the desired hour (24 hours) and minute to check for updates. To start the service press the “Start” button. If the service is running, press the “Stop” button to disable the service.

5.REST / RPC / SignalR / WebSockets

The Relay includes an extensive API you can use to build your own custom 3CX integrations. In fact, all our tools use this same API to communicate with 3CX. For API documentation, select API from the left-hand side panel.

6.Secure Socket Layer (SSL) Certificate

Coming soon!

We plan to add support for an SSL Certificate in the future so you can add additional security when communicating with the 3CX server through the Relay.

Suggest Edit

Get the Best Solution for your Business

Whether through one of our commercial products, or a custom solution built to meet your specific needs, we can help you get the most out of your 3CX investment. Call us today!

Contact Us