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.
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
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.
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
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
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
_____ _____ __ |__ // ____// / /_ // / / ___/ / /___ / /____/_____//_/_ Welcome to the 3CX Configuration Tool Help https://www.3cx.com Press ESC TO GO BACK. 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: http://192.168.1.100:5015?v=2 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.
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
1. Login as root using the password you chose during the initial install of Linux
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.
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.
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
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
sudo mkdir relay
Change ownership of the voiptools folder to your account
sudo chown -R $USER /opt/voiptools
From the new relay folder you just created, download the 3CX Relay for Linux from the VoIPTools website
sudo wget http://files.voiptools.com/LinuxRelayV16
List the name of the file downloaded:
Install unzip utility
sudo apt-get install unzip
Extract the contents of the downloaded zip file
Add execute permissions to the Setup.sh script (note case sensitive):
sudo chmod +x /opt/voiptools/relay/Setup.sh
Start the Setup.sh script:
Note: The installer will attempt to update iptables to allow traffic to reach the Relay.
Note: This step attempts to create a systemd daemon service (/etc/systemd/system/voiptools_relay.service)
See configuration file:/etc/systemd/system/voiptools_proxy.service
You should see a response in your browser similar to:
If you do not get a response from the API, ensure the following:
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:
cp appsettings.json /opt/voiptools/appsettings.json
sudo rm *.*
sudo rm Logs/*.*
cp /opt/voiptools/appsettings.json /opt/voiptools/relay/appsettings.json
sudo chmod +x Setup.sh
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.
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