Archive:FreePBX Distribution

FreePBX Distribution is a fully fledged VoIP server allowing complete customisation to your needs and works with most setups. It is an appliance, with a complete Linux setup and web manager to allow easy administration.

We have implemented FreePBX 16 and Asterisk 20. This is the latest version of Asterisk and is a LTS release so will be supported well into the future with fixes (slated to be supported until 2027). This is a complete distribution and so needs to be installed on its own machine/virtual machine. We will be setting this up on a separate virtual machine rather than the main server.

We will be configuring this system to work with the Mitel 5360 IP Phone and the Mitel 5624 VoWiFi phone so some settings are specific to the 53xx models of this phone. We will also be using Twilio as a SIP trunk so some settings are specific for this.

Prerequisites

Download the latest FreePBX ISO image. This is currently FreePBX 15 available here directly or at this website. Please do not be phased as at the moment, we will be upgrading to FreePBX 16 once FreePBX 15 is installed.
This will need burning to a DVD or writing to a USB stick. We use a USB stick and Rufus under windows to write it to a USB stick (use DD mode). This guide will cover the USB method but the CD method is very similar.

Booting the installation system

Insert the USB stick or DVD into the computer.
Power on the machine.
Press the key to bring up the boot device menu if needed.
Select the USB stick or DVD that is inserted.
When the boot menu appears, select 'FreePBX 15 Advanced Installation'.
Next, select 'Advanced Installation with Normal Video'.
Next, select 'Advanced Install with Asterisk 17 via Standard Video'. Asterisk 17 is the latest available to install from the media but we will upgrade it later. The system will now boot to the Linux installer.

Configuring the FreePBX installation

We will be using a dedicated computer with an empty hard drive. This will be a custom installation so that we can configure the system before it is installed. This guide will show you all the main options that need to be changed - there are other options if you wish to customise the installation but this is what I will be using to install the system.

Setting the date, time and time zone

Click DATE & TIME to select the correct time zone and set the date & time.
In the 'Region:' box, type or select 'Europe'.
In the 'City:' box, change 'Amsterdam' by typing of selecting 'London'.
If you are already connected to a network, ensure that the 'Network Time' switch is 'On'. This is important as this server will be used to set the times on the phones and needs accurate time to function correctly.
We will configure the time servers to use ones closer to us in the UK. Click the cog icon next to the 'On' switch.
We will change the CentOS NTP servers to Google servers. For example, double click on the first address and change 0.centos.pool.ntp.org to time1.google.com. Do this for servers 0-3 and time1-4.
We will add the main server IP address as a source too. This is typed in the top box and then click '+'.
Click 'OK'.
Click 'Done'.

Setting the keyboard layout

Click KEYBOARD.
Click the '+' button to add a new keyboard layout. We must add the new keyboard layout before removing the one we don't want.
Type 'UK' in the search box.
Click 'English (UK)'.
Click 'Add'.
Select 'English (US)' from the list.
Click the '-' button to remove this layout.
You may test the layout in the box on the right. I usually check that the '£' and '#' symbols come up when I press these keys.
Click 'Done'.

Setting language support

Click LANGUAGE SUPPORT.
Tick 'English (United Kingdom).
- Unfortunately, we cannot deselect 'English (United States)'.
Click 'Done'.

Setting the hard drive partitioning

As this is a new install, we will be configuring FreePBX to use the whole drive. We would like to use the BtrFS file system so this is slightly different to usual.

Click INSTALLATION DESTINATION.
Check that the hard drive we want to use has a tick on it.
Under 'Partitioning', select 'I will configure partitioning'.
Click 'Done'.
Under 'New mount points will use the following partitioning scheme', change 'LVM' to 'Btrfs'.
If there are already any partitions on the disk, you will have to select each one and click '-' on each one until the disk is empty.
We want to use the whole drive. At the top of the list, click 'Click here to create them automatically'. This will automatically create the correct partitions using the whole drive.
Click 'Done'.
A list of what will be done during the installation will appear which you can review. If you are happy, click 'Accept Changes'.

Disable kdump

I have no use for kdump so will be disabling it.

Click KDUMP.
Untick the 'Enable kdump' box.
Click 'Done'.

Setting the network hostname

The rest of the network settings should be OK unless you have something custom to configure. We will just be changing the hostname.

Click NETWORK AND HOSTNAME.
In the hostname box, replace 'freepbx.sangoma.local' to the hostname of your network (for example freepbx.freddythechick.net).
Click 'Apply'.
Click 'Done'.

Starting the installation

If there is any problems preventing installation, there will be a yellow bar at the bottom of the screen saying where the problem is and the section that has the problem will have a yellow exclamation mark. These sections will need fixing before you can continue.
I have added a picture of what the screen should look like for reference once everything is configured.
If you are happy with all of the settings, click 'Begin Installation'.

Entering a root password

The installation will start. While the installation continues, we need to set the root password. This will not stop the installation while you are setting this up but must be done before the installation is finished.

Click ROOT PASSWORD.
Type a password for the root user in the 'Root Password:' box.
Retype the password in the 'Confirm:' box.
Click 'Done'.

This will be an internet facing machine, even more so if exposing SSH so it is HIGHLY RECOMMENDED to type a password that fills the strength bar so that it says Strong. Use a combination of uppercase letters, lowercase letters, numbers and symbols and make the password as long as you can possibly remember. Do not use common words that may be in the dictionary or names. If you do, you will be warned with a yellow bar at the bottom and will be asked to click 'Done' again. It is HIGHLY RECOMMENDED to use a different password if you are warned of this as you will be at risk of attack.

Completing the installation

You will now be back at the installation screen - grab a cup of coffee and wait for the installation to finish.

Once the installation is finished, it will say 'SangomaOS 7.8 is now successfully installed and ready to use! Go ahead and reboot to start using it!'. Click the 'Reboot' button and the machine will reboot to the FreePBX terminal. Remember to remove the DVD/image from the drive!

First run of the web interface

Open a browser on a machine on the same network and go to the IP address of the machine. For example, if the machine is at 192.168.1.45, type http://192.168.1.45 into the address bar. If you are not sure of the address, login to the server as root and it will display the IP address of the machine. This is the first time of using the web interface so we need to set up a few items. Ignore any warnings about the server certificate - this can be set up later.
Type a username into the Username field. Avoid common usernames, such as admin and user as these are easily guessed if your server is attacked.
Type a password into the Password and Confirm Password fields. Make sure this is strong, especially if you plan to make the admin pages web facing at a latter date.
Type an e-mail address into the Notifications Email address field. This is used if there are any critical errors on the server and to inform you of automatic system updates.
You can change the System Identifier to something else if you like, this is especially handy if managing more than one FreePBX server.
Choose your settings to enable automatic updates as you would like for your system.
When done, click 'Setup System' in the bottom right hand corner.
This will take you to the home page for the server. To administer the system, click 'FreePBX Administration' and log in with the details you typed just now.
You will now be asked if you would like to activate the system with Sangoma. This is recommended to activate some of the modules we will be using later. Click 'Activate'.
Type your e-mail address. If you already have an e-mail account with Sangoma, wait a few seconds and type your password when the box comes up. Fill in any missing details if needed then click 'Continue'. If you don't already have an account, you will have to fill in your details and click 'Create'.
Under 'New Activation', type a location and then click 'Activate'. If you are re-installing an already activated system, you can go to 'Existing Deployment' and type the deployment number already activated there.
Once you have clicked 'Activate', it will then display a deployment number. This means it is successfully deployed. The deployment number can be displayed later if needed.
Click 'Skip' on the module updates for now as we need to set up the server first.
Leave Sound Prompts Language as 'English (United Kingdom)' or change this from the drop down menu if wrong.
Leave System Language as 'English (United Kingdom)' or change to this from the drop down menu if wrong.
The Timezone option should already be correct from our installation. If not, it can be corrected here to 'Europe/London'.
Click 'Submit' in the bottom left hand corner. It will take a while as it is starting to setup the system - be patient!
Unless you want to set up the firewall, click 'Abort'.
You may get a few adverts after this - click 'Not Now' to skip them.
Your system is now basically set up - you will be presented with the dashboard.
If there is a red 'Apply Now' button in the top right hand corner, press this to configure the system with the changes just implemented.

Updating the server

Updating using CentOS system updates (OPTIONAL)

The FreePBX distribution is based on CentOS 7.8, however, FreePBX very rarely, if ever, provide updates to the system unless they upgrade the distribution. You can configure the system to update using CentOS repositories for a more up-to-date and secure system.

WARNING: If you are using anything the uses kernel modules (i.e. DAHDI modules), please do not use this method to update - this will cause the modules to break as they rely on the kernel supplied to operate.

I do not use anything that relies on the kernel so shall be applying these updates.

Add the CentOS 7 update repository

At the terminal, type the following command:

yum-config-manager --add-repo https://www.mirrorservice.org/sites/mirror.centos.org/7/updates/x86_64/

We need to add the GPG key for this repository to be trusted. Type the following command:

gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7

You should see a key displayed.

Import the key so the system trusts it, type:

rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7

We now want to clear the yum cache so that it picks up the new repository. Type:

yum clean all

You can now follow the next step to update the system.

General updates

As with any Linux distribution, from time to time there are updates to the system. This will show you how to check these and install them.

Login to the system at the terminal or SSH as root.
Type yum update.
After downloading the update lists from the internet, a list may be shown showing the latest updates available. If No Packages marked for Update is shown, there are no updates available right now and you can continue to the next step.
If there are updates offered, type y to accept the changes. The updates will then be downloaded and installed. Some packages take a long time to install and the system will look like it has hung. Be patient, they will eventually install.
It is recommended that once the update is finished, you reboot the machine so that the updates are applied. Type reboot.

Updating FreePBX modules

From the dashboard, on the menu bar, go to Admin > Module Admin.
Click 'Check Online' to check the internet for updated modules.
Once done, click 'Upgrade all' on the right-hand side to mark all modules for update.
Click 'Process' to start updating the modules.
You will be presented with a list of modules to be updated. Scroll to the bottom and click 'Confirm'
Some updates take a very long time to complete, please be patient! Avoid refreshing or going back or the server could be left in an inconsistent state.
Once the current updates are complete, press 'Return' to be taken back to the Module Admin screen.
Click the red 'Apply Config' button at the top right of the screen.
Some updates rely on other packages to be updated first. Keep cycling through these steps until there are no more packages to update.

Upgrading to FreePBX 16

At the moment, FreePBX 16 is not available separately so we need to upgrade to FreePBX 16 through FreePBX 15. This can only be done once the system is updated. The biggest change of this upgrade is now supporting the modern PHP 7.4 instead of the now legacy and unsupported PHP 5.6.

From the dashboard, on the menu bar, go to Admin > Module Admin.
Click 'Check Online' to check the internet for updated modules.
Under the 'Admin' section, look for a module called 'PBX Upgrader'.
Click the > to expand the entry.
Change 'No Action' to 'Download and Install'.
Go to the top of the page and on the right-hand side, click 'Process'.
Click 'Confirm' to install the module.
Once it has completed, press 'Return' to be taken back to the Module Admin screen.
Click the red 'Apply Config' button at the top right of the screen.
On the menu bar, go to Admin > 15 to 16 Upgrade Tool.
Click the 'Check the requirements!' button.
Once it has checked, if all is well, click the 'Proceed to the upgrade process'. If anything comes back with an error, this will need fixing before proceeding.
Although you have not changed the system yet, it may complain about not using standard repositories. Under 'Non-standard Repository Servers', leave as 'Reset the repos to the defaults.
Click 'Next'.
Fill out any details you would like for the survey (this is optional), or press skip.
Read the warning message and then press 'OK' when ready to upgrade.
Please be patient, ignore any error messages and do not think the system has hung, this process can take a long time to complete. If the webpage does fail during the upgrade and you cannot access the progress of the upgrade, go to the terminal and type tails -f /var/log/pbx/freepbx16-upgrade.log which should allow you to follow the update. Once done, return to the dashboard.
Now is a good time to once again reboot the system to apply all the changes.
Once rebooted, check for module updates as per previous section.

Upgrading to the latest Asterisk version

Once all the updates have been installed on the distribution, we can upgrade the version of Asterisk to the Asterisk 18 which is the latest version as of writing.

Login to the system at the terminal or SSH as root.
From the terminal, type asterisk-version-switch.
Select the number next to the version that you would like to install - e.g. 7 for Asterisk 18 then hit enter.
Wait for the script to run through upgrading Asterisk.
When returned to the terminal, restart the machine to apply the new changes.