VOIP Lab Updated

User documentation

  • Last Updated: 01/06/2022

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 guest.img and 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

This lab will be taking place on the lan of spoke3, which was created in previous labs. This network should already have a vlan. Before starting, you need to ssh onto the switch and make sure that this vlan has an access port setup. This port is needed as the phone will eventually be connected to this port via ethernet, and it can be used as an access point to the network for your computer when the wireless connection isn't working. 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

Make sure to "write mem" afterwards.

Starting up the 3CX vm

Note: For the purposes of this lab, we renamed the guest.img and guest.xml files to 3cx-guest.img and 3cx-guest.xml.

Next, edit name and file path for the img in the 3cx-guest.xml file and add a network interface for vlan 101, as we will be using spoke 3's LAN. 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/hostname file and the /etc/network/interfaces file in the VM to reflect the IPs you'll need:

auto ens2
iface ens2 inet static

In this case, we will be using ens2 since that is the interface that we gave our MAC address and connected to vlan 101 in the 3cx-test.xml file.

Note: After changing /etc/network/interfaces make sure to ifdown and ifup whatever interface was changed.

Before continuing, try to ping

Now, resize the storage given to 3cx-test. Instructions on:

Before installing 3cxpbx, you must run the following commands:

apt-get purge locales
apt-get install locales
dpkg-reconfigure locales

Make sure you select en_US.UTF-8 after running dpkg-reconfigure locales.

Install dphys-swapfile and 3cxpbx

wget -O- | sudo apt-key add -
apt update
apt install net-tools dphys-swapfile
apt install 3cxpbx

Installing 3cxpbx should put you into a configuration prompt that starts with a licensing and agreements section. When it asks you to select how you would like to run the tool, select the first option using the web tool. Then, you will be given a url to go to in your browser where you will continue to configure your 3cx 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).

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.

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.

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

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 need to add a line to the subnet we set up in the DHCP config like so:

 option tftp-server-name "";

Remember to run "service isc-dhcp-server restart" after editing this configuration file.

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

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 the correct vlan
  • 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.

Note: If you correctly provisioned the phone, but it doesn't ring when called, click on your extension in the administrative window and go to options. Deselect any restrictions.

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 that the MAC address for each device was entered correctly in the web application when provisioning.

If your phone was given an IP but "no service" popped up on your phone, go into the your spoke where dhcp is set up and type "cat /var/lib/dhcp/dhcpd.leases". This shows you all of the temporary IPs assigned by dhcp. If you see a lease for your phone, this means that dhcp gave your phone an IP when it wasn't provisioned properly. So, go into the file and delete the lease. Now, factory-reset your phone again. Hopefully, "no service" has been replaced with an extension.

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.

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.