Frequently Asked Question

FreePBX 17 - Install

Last Updated 7 months ago

* This is a copy of an article I wrote on my blog, September 2024.

Before you start, if you are upgrading from an existing configuration, you should read the gotyas before going any further, because you may endure some pain, if you're starting from scratch, you can continue on as it wont apply to you.

You will need to take precautions if you are doing this installation to replace an existing and functioning PBX on your network, with netinstall you'll get a DHCP issued IP that avoids conflicts (we'll set static IP as the last process), you can even use the servers real hostname, but when it comes to FreePBX configuration time, you risk Trunk conflicts, you don't want your new server with trunk registrations until you formally commission it, surely I don't need to tell you what happens if conflicts occur here

Download Debian

Download the latest netinstall version of Debian 12 from https://www.debian.org/download

if you're installing Debian 12 from a VPS control panel, you might need to find out what type of template they are using, it might be the full install, and, like if you have already a full install of Debian 12, that's fine, your installation might be a lot quicker with existing required packages installed, apt will know.

You will need to take precautions if you are doing this installation to replace an existing and functioning PBX on your network, with netinstall you'll get a DHCP issued IP that avoids conflicts (we'll set static IP as the last process), you can even use the servers real hostname, but when it comes to FreePBX configuration time, you risk Trunk conflicts, you don't want your new server with trunk registrations until you formally commission it, surely I don't need to tell you what happens if conflicts occur here

Etcher (*nix) or Rufus (win*) will make your life easier creating a bootable USB image on a flash drive, but command line users can also use direct copy to the device, but don't use a partition, eg: if dmesg shows your USB as sdg then

cp /path/to/debian-12.6.0-amd64-netinst.iso /dev/sdg

sync

Install Debian 12 from USB

Boot from Debian USB, and select the Graphic Install option (this wont install a GUI desktop)
Select your Language
Select your Country
Select your keyboard layout
Enter a host name for the server
Enter root password for the server and confirm
Enter the full name for a normal user account
Enter the login for the normal user account
Enter the password for the normal user account and confirm
Select the servers time zone
Select the “Guided use entire disk” option unless you want an advanced setup
Select the disk where you are installing Debian 12
Select the “All files in one partition” option
Select the “Finish partitioning and write changes to disk” option and continue
Select “yes” to confirm you want to write changes to disk
Select “no” to scan more media if asked
The installation of base packages will continue
Select a Country close to where the server is for updates, (use your country default)
Using the netinstall version of Debian 12, your packages will download during installation
Select the local mirror you prefer, I'd use the recommended
Unless you really need to use an outbound proxy, you can leave that field blank
E.T. is happy, so he never needs to phone home, he's also not wanting attention, select NO to entering popularity contest and sending data back to Debian.
Only select “SSH Server” and “Standard System Utilities” NO Desktops on servers! So de-select debian desktop and Gnome
Installation should be complete, remove the USB drive and press continue to reboot
Once the system boots up, login as root and run the following commands, this makes sure your system is fully updated and enables "root" ssh access (we'll tighten this later) so whilst setting everything up root can get ssh access without fussing with su or sudo.

apt-get update && apt-get upgrade 

apt-get install net-tools htop screen tshark vim sngrep

PermitRootLogin no
Match Address  YOUR.PCs.LAN.IP
        PermitRootLogin yes

service ssh restart
ip a

Install FreePBX 17

At this point, you can start the FreePBX 17 Installation by ssh pbx.ip and copy/paste the following commands to run
```
cd /tmp 

wget -O - https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh | bash
```
The bash script will install the necessary dependencies for FreePBX, followed by the FreePBX software itself.

You will find detailed installation logs at /var/log/pbx/freepbx17-install.log

Now configure FreePBX as you would normally from the web login page (https://PBX.IP.ADDR) and either start fresh from scratch, or by grabbing a full backup from an earlier release (supported back as far as FreePBX 14) and restoring.

I suggest, with all servers, for your user and root, login as each via ssh and setup your ssh keys to login to the PBX server passwordless.

If you want to secure SSH even more than we did earlier, an alternative would be to change from allowing root with password from your PC, to only allowing root with ssh keys, and to a number of restricted hosts, example, I first globally deny, then use the match statement where I include my desktop, laptop LAN IPs, my wireguard IPs (which are direct and not the WG servers IP) for my devices and then I set prohibit-password which forces using ssh keys. Multiple addresses are entered no-spaces comma separated, you can also include a /CIDR eg:

PermitRootLogin no

...

Match Address 100.1.1.1,100.100.5.5,100.111.9.0/24

       PermitRootLogin prohibit-password

...save, and ...

service ssh restart

Restoring Setup from FreePBX 14/15/16

Known and Found Gotyas

Firstly, I strongly encourage you to start fresh if you only have a small number of extensions and you're currently on v14, we saw a number of banner ajax errors during restore but the restore frame does not have a scrollback to find the culprits, the restore process with FreePBX v14 also killed itself around trying to update firewall with the IPs, the browser couldn't connect, ssh nor even the directly connected console itself which froze, requiring a reboot to regain entry to the system, going back to the browser we got the not-so smart firewall page again, we opted to disable it, and from then on things were OK, we'll bring over our old firewall rules file to re secure it later. I will add upon initial installation, before the Restore, the smart firewall section worked fine with no issues, it was only whilst running Restore that FreePBX crapped out on us.

FreePBX 17 installs Asterisk 21, which no longer supports chan_sip or the Macro dialplan application, this could lead to issues if your trunk provider and peers don't support pjsip - they should, the removal of chan_sip has been coming for a long time, it was marked deprecated and unsupported since Asterisk 17 back in 2019, but many years before that everyone was warned it was being retired, it is a very old and limiting protocol, it was further warned Asterisk 21 onwards will have no chan_sip code in it, so if your provider does not offer pjsip, they've been more than just asleep at the wheel and don't deserve anyone's business, Asterisk, Broadsoft, and others, have supported both protocols for a very, very long time, pjsip although first written in 2002, was released in 2005, that's nineteen years ago.

TLDR - Chan_sip removal did NOT happen overnight, it's been well publicised, and coming for years.

Macro application in dialplans and AGI's have likewise been deprecated for some years. Apps using them should be using GoSub, I manage FreePBX versions from 14 to 16, none of them have that problem, so unless using an ancient third party module you should be OK, if this is a new install, it wont matter anyway.

Fear not however existing chan_sip users upgrading, because the FreePBX 17 installation will convert all chan_sip trunks and peers to chan_pjsip during the restore operation.

Restore Config from Backup

You need the "full" backup file from your older version of FreePBX, this should be as easy as grabbing the Weekly_Full/timestamp-fpbx_version-foo.tar.gz file .. because, you do have weekly full backups, right? Get the backup file and put it where you can upload it to your new FreePBX 17 PBX, and use the Backup and Restore module to restore it, once it's done, carefully check the output, then click confirm if you're happy with it to do its magic.

Now I recommend rebooting, this is of course optional, but I like to make sure everything comes up nicely as it should, since these are mostly unattended servers, this should allow you to catch and resolve any issues now - preventing nasty midnight surprises later on (because Murphy's Law No. 2 - bad things never happen during normal business hours ), then once again go over everything to make sure it's working as it should be - extensions, trunks, IVR's, custom recordings, your cron tasks, your LE certificates - the works!

Finishing Up

Protect ChanSpy, it might be disabled by default, but if you enable it down the track, you want to make sure you are the only one who can access it, especially if you get distracted and forget to disable it when you're finished.

All things going to plan, you should now have a successfully working installation of FreePBX 17 running your phone system, once you are done testing and validating, there are two more tasks to perform before we move it into production, set static IP and setup automatic updates.

Firstly, we need to change to a more permanent static IP, I recommend using console for this task, if this is a new FreePBX server, pick a free IP on your LAN (outside your DHCP range) or if you're replacing an existing system, use your previous static IP on this machine, if the old PBX is still running, pull the network cable on the new one until you're ready to bring it live, or issue a shutdown on the old one if you prefer to make it live now (remember my suggestion for using console).

To get the correct interface,

cat /etc/network/interfaces

So we see our interface is eno1, and for example we use static IP 100.100.100.111 with a /24

Currently, our interface uses DHCP

allow-hotplug eno1

iface eno1 inet dhcp

We need to erase or comment-out the above two lines, DHCP might be OK for PC's, but it's not acceptable for Servers, so we need to remove it and add in a static, edit /etc/network/interfaces

auto eno1
iface eno1 inet static
        address 100.100.100.111/24
        network 100.100.100.0
        broadcast 100.100.100.255
        gateway 100.100.100.1
        dns-nameservers 100.100.100.254

Save the file and run

 systemctl restart networking.service

I'd also suggest rebooting about now to once again, make sure everything comes up as you expect.

Lastly, we should set up unattended updates, else the OS will not by default using netinstall method at least, upgrade itself and you'll need to login and do it manually. As root, issue the following

apt-get install unattended-upgrades apt-listchanges

Next use your favourite editor and edit /etc/apt/apt.conf.d/50unattended-upgrades, search for and uncomment (remove the "//" before) and add in your email address like so

Unattended-Upgrade::Mail "your@email";

and uncomment the next statement

 Unattended-Upgrade::MailReport "on-change";

save the file, and enable auto updating by issue the following and selecting Yes

 dpkg-reconfigure -plow unattended-upgrades

Next we have to tell systemd when to run it, this is a phone system, and systemd does not know this nor care, I have seen countless occasions in the past where the braindeadness of systemd will update and on occasion reboot the machine during peak times, so we must tell it we want updates in the middle of the night when the impact is minimal.

Run the following systemctl command and copy/paste the Timer section below only into it (the double OnCalendar is not a mistake, the first clears existing timer, the second sets new time for Downloading updates

systemctl edit apt-daily.timer
[Timer]
OnCalendar=
OnCalendar=03:30
RandomizedDelaySec=0

save the file, then reload

systemctl restart apt-daily.timer

next, we need to do much the same for the upgrade process itself

systemctl edit apt-daily-upgrade.timer

[Timer]
OnCalendar=
OnCalendar=04:30
RandomizedDelaySec=0

  (save...)

systemctl restart apt-daily-upgrade.timer

You can check both of these to ensure your edits are saved and active by running

systemctl status apt-daily.timer
systemctl status apt-daily-upgrade.timer

You should see your new times in the output.

I'd also suggest editing /etc/apt/listchanges.conf and change the default email "root" to the email address you used above.

Congratulations... you're all done with a working FreePBX 17 PBX service