User documentation

  • Last Updated: 08/10/2018

To learn about VoIP, we are going to create a real VoIP system using 3CX, an enterprise-grade PBX software. One new part of this lab is that you will be connecting your setup to the internet for the initial setup of 3CX.

IMPORTANT: Before connecting to the internet, ask a teacher/network administrator to get approval.

Note: for this lab you will need the 3cx-guest.img and 3cx-guest.xml files. Make sure to install these files using the methods described on the wiki if they are not already located on the server:

Connecting to the Internet

First, you need to find an ethernet port that goes to the internet of your school. Once you've found it, create an access port for vlan 999 on your switch. Now plug your school's internet into the access port for vlan 999. Make sure that the link light on the switch turns green. If it does not, bpduguard might be your problem. Research "bpdufilter" for a fix.

Starting up the 3CX vm

Next, edit the 3cx-guest.xml file to add two network interfaces, a WAN vlan (999), and a LAN vlan (any number not yet configured). After that, make sure to add the vlan bridges on the host as well. Then, define and start the vm:

root@labsrv1 14:21:46 
 > /data # virsh define 3cx-guest.xml

root@labsrv1 14:21:46 
 > /data # virsh start 3cx-guest

root@labsrv1 14:21:46 
 > /data # virsh console 3cx-guest

Next, edit the /etc/network/interfaces file in the VM to reflect the IPs you'll need:

# The primary network interface
auto eth0
iface eth0 inet dhcp

# Phone-facing interface
auto eth1
iface eth1 inet static

In this case, eth1 is the interface on the phone's side, while eth0 acts as a kind of fake wan interface. Restart the networking service. Now try pinging as well as the gateway for eth0 to make sure you can access the internet from the VM.

Use the following command to reset any previous configuration. Make sure to select the option to use the web configuration (option 1).

root@3cx-guest:~# 3CXWizard --cleanup 

Connect to either network and go to either <your_wan_ip>:5015 or to configure the phone system.

Web Configuration

At the configuration screen, you'll be asked for your license code. Go to and sign up to get a valid license. It will be emailed to you after you confirm your email.

After you've entered your license, set up your username and password. Just use the standard NEATRack username and password. When asked if you want to use your public IP, select No and manually enter the device's WAN address. On the following page, select dynamic. Make your FQDN whatever you want and leave ports as-is, then choose WAN as the default network adapter.

After the FQDN setup is finished, select 3 digit extension length. Enter an admin email you can access. For the operator extension, give it a name and enter an email you can access. Leave country and language alone. For Registration Details you should see the information you entered to get your license key. Create a company name and click finish.

After setup is complete, you should be able to access the web configuration through either WAN or LAN using http on port 5000 (5015 is just for setup).

DHCP Server

To greatly simplify connecting devices, we will set up a DHCP server on our 3CX VM. We will be using isc-dhcp-server just like in the KVM and Static Routing labs. Set the DHCP domain name to 3cx.local and add 'authoritative;' Set up dhcp on the LAN (, including just a range and a broadcast address. You don't need to worry about setting a gateway as the phone system will be offline. Don't forget to restart the service when you're done. Test the server by connecting a device and make sure it gets an IP in the appropriate range.

WAP Configuration

If you would like to connect a device via a wifi network, you have two options. The first is to configure a WAP to create the wifi. If you have a WAP, you can most likely find an online configure guide.

The second option is to configure a Raspberry Pi as a WAP. You will need to use one of these options for any computer acting as on a wifi network.

Provisioning Phones in 3CX

3CX is a phone client that supports multiple different phone solutions. As long as you have internet connection, 3CX probably has a way to connect you to the server. They do this by creating a custom tunnel from whatever machine you are on to the server you are trying to access. Lucky for you, 3CX does this automatically on soft phones.

The objective of this lab is for you to call from one phone to another through 3CX. The way that you achieve this, however is up to you. There are a few options you have for different phone types to use:

  • Hard Phone: Aastra, Grandstream, etc. SIP phones plugged into the switch
  • Soft Phone on Windows/MacOS: Machine running Windows/MacOS connected to the 60 or 80 network*
  • Soft Phone on Linux: There is no guide for this below, but it is possible with a WINE setup. At the time of creation, there is no tool that supports this functionality but one may be created in the near future.*
  • Soft Phone on iOS and Android: This setup requires the device to be connected to a WAP (Wireless Access Point) on the network. There is a guide to do this here
* = These machines need access to the internet and access to the server separately. They will be moved around. They also need permissions to run executables.

There will be a guide below for how to provision each of the following phones. While you can do two of the same, we would recommend trying out as many new ways as possible.

Hard Phone Provisioning

Hard phone provisioning is relatively simple. This is used when you have a physical VoIP phone that 3CX supports. You can check to see if your phone is supported here:

If your phone is listed here, you can continue with hard phone provisioning. Make sure your phone is initially unplugged before we begin. For the purposes of this example, I tested using a Grandstream 1405.

Most hard phones run through Power over Ethernet (PoE). This means they can either take power from an Ethernet port or from a power adapter. An image of the back of a GXP1405 is below:

There are two Ethernet ports on the bottom of the phone. The first, named "PC" is used as a passthrough. This means that you can plug in another machine to that port if the phone is working and get access to the network. The LAN port is the input for the phone and is therefore necessary to connect to the network.

You can see that there is a power plug in addition to the Ethernet ports. You don't need to use the power adapter IF your switch is PoE. To figure out if your switch is PoE (on a Cisco switch), look the model number, normally located in the top right. A PoE switch would look like so:

While a non-PoE switch would look like this:

Reset your phone to factory defaults. You can search the internet on how to do this; each phone is different.

Enter the 3CX Web Configurator. Click on the Extensions tab on the left hand side and add an extension. Make sure to give your extension a number and name (either first, last, or both work) so that you know which phone is which. Click on the Phone Provisioning tab on the top bar.

Under Your Phones, you will see that there is a drop down menu with 3CX Client listed. Click the add button above that.

A menu will come up with two options. Choose your phone model from the drop down. If your phone model isn't listed, you can try selecting the closest number to your phone, but it isn't guaranteed to work. Find and enter the MAC address into the blank below. MAC addresses follow the format "xx:xx:xx:xx:xx:xx", sometimes without the colons and can usually be found on a sticker or label on the phone. Click the ok button to close the pop up window. If this is the first hard phone you are provisioning, be sure to copy the provisioning link under Provisioning Method (in the IP Phone category). Make sure the IP address is the 3CX LAN address, and if not change it. Make sure the selected interface (Under the IP Phone category on that page) is the LAN network. Click ok again to save the extension.

If this is your first hard phone, you will need to add the provisioning link you copied to your dhcp server. This will tell hard phones where the 3CX server is on the network and allow them to provision. To do this, we configure an option, in this case option 66. We will be adding a line to the subnet we set up in the DHCP config like so:

 option tftp-server-name "";

Without this option, hard phones will get an IP but will not provision and connect to the server.

After that, plug your phone's ethernet port into the switch on your LAN vlan. As a reminder, you can change a port's vlan with the following:

trainswitch(config)#int f 0/19                                                  
trainswitch(config-if)#switchport access vlan 80

You can now plug the SIP phone in. If your switch is PoE, your phone should start to turn on when you attach it to the switch. If it isn't, plug in a power cable to your phone after plugging in the Ethernet cord and your phone will boot.

From here on your phone should boot then start provisioning on its own. Most phones restart when they correctly provision and either show their extension number or 3CX when they are provisioned. Try calling another phone to see if the phone is provisioned.

If the phone is not provisioned, it will probably say something along the lines of no connection and instantly hang up or give static whenever a call is attempted. Always try rebooting the phone from scratch first. Some common problems to check if the phone doesn't provision:

  • Make sure you entered the MAC address correctly
  • Make sure you have the phone on vlan 80
  • Make sure the phone is supported by 3CX and you selected the correct model
  • Make sure your extension saved by pressing "ok"

If none of these fixes correct the issue, there is a chance your phone doesn't work with 3CX.

Soft Phone (Windows and MacOS) Provisioning

Windows/MacOS provisioning is relatively easy due to 3CX automatically creating a tunnel from any network to the server. This is especially easy because you are already on the correct network.

Connect your computer to the 80 network for the time being.

Navigate to the 3CX web configuration panel. Click on Extensions on the left menu and click add. You must use a new extension when provisioning.

Type in an extension number that isn't already in use and a name of some sort to identify the phone. Choose an email address you can access on the computer that will be the soft phone. Go to the phone provisioning tab and make sure the network interface for registration and provisioning is the external IP. Click ok to save your configuration.

Connect to a network where you can access the internet in order to check your email. 3CX automatically sends an email with a file attached. This is your configuration file. Download it somewhere you can access it. Also, there are 4 links at the bottom of the email that lead to the clients 3CX uses. Click the link corresponding to your OS and download the client. Links to the clients are also below.

After you have these two items downloaded/installed, open up the client. It will prompt you if you would like to autoprovision. Select cancel. Then, DRAG the .3cxconfig file overtop of the application. After that, click settings (bottom right) -> configure accounts -> account name. Enter the LAN address of the server into the 'In Office' box and click ok.

Soft Phone (Android/iOS) Provisioning

Android/iOS phones are easy to provision. This is possible on any device with a connection to your WAP. Download the 3CX app and connect your computer to the 80 network.

Navigate to the 3CX web configuration panel. Click on Extensions on the left menu and click add. You must use a new extension when provisioning.

Type in an extension number that isn't already in use and a name of some sort to identify the phone. Choose an email address you can access on the phone that will be the soft phone. Go to the phone provisioning tab and make sure the network interface for registration and provisioning is the external IP. Click ok to save your configuration.

Go onto your device. Download the attachment in the email, then open it in 3CX. The attachment should lead you right into 3CX. Once in 3CX, click the 'more' tab in the bottom right, then go settings -> accounts -> your account and set the local PBX IP to Make sure you are connected to the WAP and have an IP address.

General Testing

The first step to see if a phone is connected to the 3CX server is to check the Extensions page in the web interface. If the phone is connected, there will be a green circle next to it. If you have two or more devices connected, you should be able to call each phone from each other phone on the network. To call another phone on the network, simply enter its extension number in the 3CX application or on the physical phone and press call/dial. If the device you are calling is connected and the application is running, it should ring and you can answer it.

Troubleshooting Provisioning

The first thing to check if you are having issues provisioning your phone is the device's network status. Ensure that the device has an IP address and is on the 80 network.

Make sure your 3CX server can access the internet by pinging google. If that isn't working, make sure the server is properly connected and has an IP address. Use "dhclient eth0" if you are connected and don't have an IP address.

If you are not receiving an email from 3CX, make sure that you set the interface as the external address when adding an extension. If not, you may need to delete the extension and re-add it.

If you are have opened the attachment on your soft phone, but it still won't connect, make sure that you have set the local address for the 3CX server. The phone may say that it is waiting for network, but that doesn't mean that it won't work. Try testing anyway.

If you are having problems with your hard phone, make sure that you have factory reset the device. If the phone has an IP address, but still won't connect to the system, make sure you have added option 66 to your DHCP server (explained with Hard Phone Provisioning)

The Fun Part

Once you have 2+ phones set up and working, try experimenting with the settings and features in the web interface. There are a ton of cool things you can add or modify in the phone system, and it's definitely worth checking out. For example, you could set up conference calls to allow more than two people to call at one time.


HardPhone1.JPG (2.43 MB) HardPhone1.JPG Redmine Admin, 12/18/2017 02:28 PM
PoESwitch.JPG (887 KB) PoESwitch.JPG Redmine Admin, 12/18/2017 02:41 PM
PoESwitchNo.JPG (846 KB) PoESwitchNo.JPG Redmine Admin, 12/18/2017 02:41 PM