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.

1.1.Why a relay is needed?

The Relay is needed because the 3CX Call Control API only accepts connections from “localhost”. Given
that 3CX does not want any non-3CX software installed on the 3CX server, this 3CX restriction makes a
“relay” mandatory.

1.2.What are the benefits of a relay?

In addition to making it possible to install our add-ons on a separate server, the VoIPTools Relay also
simplifies our upgrade process when 3CX releases a new service pack or version upgrade. Because our
add-ons communicate with 3CX through our relay, often times all we have to do is upgrade our relay
and all of our applications instantly become compatible with the new version of 3CX.

2.Important Tools

To complete the following steps, you will need to download and install two free tools — putty (SSH
client) and FileZilla (for copying files to the 3CX server). You can download these tools using the
following links:




It is assumed that you have access to the 3CX server command line either directly on the server console,
or via a tool like putty. All the commands below assume you are logged into the operating system with
root permissions.

Note: When you installed 3CX you were required to enter a password for the user “root”


If you are installing both the operating system and 3CX at the same time (using an iso) you won’t initially
have access to the operating system command line because the 3CX installer has exclusive control of the
command line.

     _____  _____  __
    |__  // ____// /
     /_ // /      /
   ___/ / /___  /  

Welcome to the 3CX Configuration Tool


Select how to run the tool:
(1)	Using a Web Browser
(2)	From Command Line
Enter option: _

To issue Linux commands you will need to make a separate putty connection using either the public IP
address of the server (in the case of a hosted server) or the private IP address of the 3CX server. To
display the server’s address, select “1” on the Linux command line:

(1) Using a Web Browser.

The following prompt will display with the 3CX server’s IP address listed within the URL in green:

Starting PbxWebConfigTool…
Launch this url from a browser on another machine:
TIP:  If this is a cloud machine and the link shows a local IP address then you need to replace the local ip with your public IP Address.

Static local (private) IP address

As a 3CX best practice, you should ALLWAYS configure your 3CX server with both a static internal
(private) and an external (public) IP address. Because our add-ons are typically installed on a separate
server (not on the 3CX server), it’s important that the IP address of the 3CX server never change. Using
an IP address obtained through a DHCP server can potentially cause your IP address to change from time
to time.

1. Login as root using the password you chose during the initial install of Linux

Linux Login

5.AWS Lightsail: Web SSH, FileZilla, Putty

AWS Lightsail is a low-cost hosting platform provided by Amazon. For small 3CX environments, you can host the Linux version of 3CX for as little as $5 per month. When installing 3CX Express for Lightsail, a Linux user “admin” is automatically created. No password is required, rather, you must download a security key from Lightsail.

SSH key basics

An SSH key is like a password, but much longer and, consequently, saved in a file on your computer. In addition to being a password, it can provide additional features related to security. Although I’m calling it a key here, it’s actually a key pair, with Amazon holding the public key and you holding the private key.

Once you’ve logged into your Amazon Web Services account with your username and password, all other interactions require SSH keys rather than passwords. At a minimum, you need one SSH key pair for each Amazon region you use and you can have up to 100 key pairs per region.

For each Amazon region, one of your key pairs is the default pair. When you create a new Lightsail instance, it will use the default pair unless you specify differently. When you create a new instance, the link to Change SSH key pair is right below the link to Add a launch script.

Your initial key pair is set up when you create your Lightsail account. If you love to be confused, or if you have another, better reason, you can set up more key pairs by clicking the Account button at the top of your Amazon Lightsail dashboard. One of the tabs on the page that appears is named SSH keys. This is where you create new key pairs. After you create a key pair, you download its private key, which is a small file that ends with .pem.

One of the additional security features of SSH keys is confirmation that you’re actually connecting to your own instance and not being clandestinely misdirected to a charnel house trying to steal your private key. However, the first time you connect to your instance from any of these programs, you’re likely to get a message saying The server’s host key was not found in the cache. If this is your first connection, click the Yes button to trust the connection.


We recommend you download the Relay directly to your 3CX server from a SSH session using wget (see instructions below).  Alternatively, you can download the Relay from our Website to your local PC using a browser, then upload the files to your 3CX server using a tool like FileZilla or WinSCP.


To upload the Relay to your hosted 3CX you need a Secure FTP (SFTP) client tool. A good free tool is FileZilla. You can download FileZilla HERE here:

Once you have installed FileZilla, the hardest part is figuring out what to do after you start the program. You need to get to the FileZilla Site Manager. Here are three ways to do that: click the icon immediately below the File menu, pick Site Manager… from the File menu, or press ctrl-S.

Otherwise, the FileZilla user interface is a breeze compared to the one for PuTTY. On the left side of the FileZilla site manager you create, organize, and delete site configurations. On the right side there’s a section with four tabs, but everything you need to enter is on the first one, General.

First click the New Site button and give this connection a name. For Host, enter the public IP or domain name of your instance. For Protocol, select SFTP – SSH File Transfer Protocol. For Logon Type use Key file. For User enter ec2-user. For Key file, browse to and select your .ppk file. Finally, click the Connect button, which will both save this site’s configuration and connect you.

The list of files on the left are on your computer and the list on the right are on your Lightsail instance. Dragging files from one side to the other copies them between your computer and your instance.

Here’s the FileZilla USER GUIDE.


One really nice feature of Lightsail is an integrated web-based SSH client. To access the Debian command line, you need to use an SSH client. Examples of standalone SSH clients include tools like “putty” and “WinSCP”. Obviously, a web-based SSH client has some limitations (can’t use a mouse for example), but it provides the convenience of instant access without having to download, install, and configure an SSH client. You will use an SSH client to create folders, set file permissions, and other “fun” stuff.


Download WinSCP HERE. For the most part it does the same thing FileZilla does, but it has some additional features, including a tighter relationship with PuTTY. The feature I like best, however, is an integrated text editor that lets you see what’s inside files just by double-clicking on the file’s name.

When you start WinSCP it also automatically opens the equivalent of FileZilla’s site manager, which is a window called Login. From there however, we’re back to PuTTY-like hidden configuration options.

In the site area on the left, pick New Site. Then, on the right, File protocol should be SFTP; Host name is the public IP number or domain name of your instance; and User name is ec2-user. Leave Password blank.

Now click the Advanced… button. (If instead you click the dropdown triangle on that button, then select Advanced… from the menu that appears.) In either case, a PuTTY-like window appears with categories on the left and configuration options on the right. Ignore it all except the Authentication sub-category under the SSH category. That’s where you’ll find the Private key file field. Click the icon at the end of the field to browse to your .ppk file. Then click OK, then Save, then Login.

WinSCP defaults to an interface similar to FileZilla’s, but if you select the Options menu, then Preferences…, then Interface (under Environment) you can change it to a Windows Explorer-like interface. In this case WinSCP shows you only the files on your Lightsail instance. To copy files back and forth you drag them between WinSCP and Windows Explorer. WinSCP also has a Properties button that you can use to change the ownership or permissions of files, which otherwise you’d have to do with chown and chmod commands in a bash terminal connection.

Here’s the WinSCP documentation.

6.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.   Our tools are always installed on a separate Windows server.  To enable our tools to communicate with the relay, you will need to open (port forward) a couple of ports on your firewall, pointing to the 3CX server:

TCP 8800 (Relay)
TCP 8801 (Optional Exporter proxy)

Note:  Port 8801 is optional and only needs to be opened if you are using our 3CX Exporter add-on

Create Folders

Using a SSH client (WinSCP, Putty, etc.) create the following folder structure on your Linux server.  Note that the Relay assumes this path so this path is required, and remember Linux is case sensitive, so be sure to create the folder structure in all lowercase.


sudo cd /opt
sudo mkdir voiptools
cd voiptools
sudo mkdir relay
cd relay

Folder Permissions

Change ownership of the voiptools folder to your account

sudo chown -R $USER /opt/voiptools

Install Relay Using Wget

From the new relay folder you just created, download the 3CX Relay for Linux from the VoIPTools website

sudo wget

List the name of the file downloaded:

ls *.zip

Install unzip utility

sudo apt-get install unzip

Extract the contents of the downloaded zip file

unzip <downloaded-file-name>

Add execute permissions to the script (note case sensitive):

sudo chmod +x /opt/voiptools/relay/

Start the script:

sudo ./opt/voiptools/relay/


  1. Register the Relay using your license key.  The contact information should be the end user (customer).  Be sure to include the Reseller’s company name if purchased through a 3CX Partner.

  2. Choose “Next” to move to the configuration screen.  The configuration screen lists a number of steps that can be completed by the setup program.  If you want to skip any of the tasks, simply remove the checkmark (tick) from each option.
  3. Server Bindings:  Typically the defaults are sufficient, but you can use this field to define the URLs accepted by the Relay/REST API.  You can enter multiple URLs separated by a space.  For example:
  4. Relay Port:  This is the port VoIPTools products use to communicate with the Relay.  By default, this port is closed and must be opened on your firewall.  If you need to change the port number used by the Relay, you can change it here.

    Note:  The installer will attempt to update iptables to allow traffic to reach the Relay.

  5. Relay Daemon:  The Relay should start automatically when the 3CX server is booted and be configured to run at all times so our add-ons can access the 3CX Call Control API.  A Linux “Daemon” is analogous to a Windows service in that it ensures the Relay is always running.

    Note: This step attempts to create a systemd daemon service (/etc/systemd/system/voiptools_relay.service)

  6. Proxy port:  This “optional” port is used by 3CX Exporter.  If you do no use Exporter, it is not necessary to open this port on your firewall.  This is the public port used by the PostgreSQL proxy.  The proxy enables 3CX Exporter to synchronize 3CX data with an external database.
  7. PostgreSQL Settings:  This button displays information required to setup 3CX Exporter
  8. Proxy Daemon:  This proxy is only needed if you are using 3CX Exporter.  Like the Relay daemon, this task sets up a Linux daemon to ensure the proxy automatically starts when the server boots.  This step configures a daemon using systemd.

    See configuration file:/etc/systemd/system/voiptools_proxy.service

  9. Save:  This button runs each of the selected setup tasks.
  10. Start / Stop Relay:  Once the Daemon is created (steps above), this button can start or stop the 3CX Relay daemon (service).
  11. Start / Stop Proxy:  If you chose to set up the proxy daemon, this button is used to either start or stop the Proxy daemon (service)


  1. Test the Relay:  When you press the “Start Relay” button, the daemon should start and the status field should change from “Stopped” to “Running”.  You can confirm the Relay is running by testing the REST API using your browser.  To test the API, Open your browser and enter the following URL:

    You should see a response in your browser similar to:


If you do not get a response from the API, ensure the following:

  • The Relay started successfully
  • No other application is using the configured port (default: 8800)
  • The firewall was configured to port-forward the port (default: 8800)
  • Your web server bindings were configured properly
  • Your URL is formatted properly.  Example:

7.Upgrade Relay

Upgrading the relay can be as simple as deleting the existing relay files and reinstalling the new version.

To preserve your previous settings, including your license registration information, you may wish to save the appsettings.json file.

The recommended steps are:

  1. Open an SSH session (WinSCP or Putty for example)
  2. Stop the current Relay by running the setup program and navigating to the setup screen where you can stop the relay and Exporter proxy service.

    cd /opt/voiptools/relay

    sudo ./Setup

  3. Exist the setup program (alt+C)
  4. Preserve your existing settings and license information by copying the existing appsettings.json file to an alternate location.

    cp appsettings.json /opt/voiptools/appsettings.json

  5. Delete the existing Relay files

    sudo rm *.*

  6. In addition to deleting the Relay files, you may wish to also delete remaining log files.

    sudo rm Logs/*.*

  7.  Having deleted the existing relay, you can follow the standard installation procedures.  However, before running the setup program, remember to copy back in the appsettings.json file you preserved in step 4 above.

    cp /opt/voiptools/appsettings.json /opt/voiptools/relay/appsettings.json

  8. Add the execute permissions to the new file copied with the new relay.

    sudo chmod +x

  9. Run the Setup script to confirm your previous settings and license information was preserved, and start the Relay.

    sudo ./

  10. Start the Relay and (optionally) the Exporter Proxy.
  11. Confirm the Relay is responding to requests by opening a web browser and issuing the following commands:

    http://<server-ip or FQDN>/Api/TestConnection
    http://<server-ip or FQDN>/Api/Extension/<number>

    For the first command, you should receive a “true” response.  For the second command, you should receive extension configuration information.

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