Run a phone system with FreePBX

What you will set up

FreePBX is a phone system for an office or a household. You create extensions, voicemail, queues and call routes in the browser, and FreePBX writes the configuration for Asterisk, the program that carries the calls. Desk phones and phone apps connect to it over SIP.

FreePBX is different from the apps in our other guides. Sangoma's installer takes over the whole server and installs its own web server, database and firewall, and it runs as root. It supports only Debian 12, so it needs a server of its own, freshly installed with Debian 12.

Every step below was run on a fresh Melonslab VC-P Alloy (2 vCPU, 8 GB) with Debian 12:

• FreePBX 17.0.33 with Asterisk 22.11.0 installed in about 30 minutes, and the admin account was created in the browser.
• The web interface got a Let's Encrypt certificate from FreePBX's own Certificate Management.
• Two extensions registered from SIP clients on another network, and a call between them carried sound both ways through the server, with no lost packets.
• With the firewall on, SSH and the web interface answered only the trusted address and timed out for everyone else. A SIP client from an untrusted address could still register and call, through the Responsive Firewall.
• SIP scanners showed up within two hours and tried accounts such as 100 and 10000. Asterisk refused every attempt.
• A backup took about a minute. After an extension was deleted, a restore brought it back, and the phone registered again with its old password.
• Everything came back by itself after a reboot.

The server used between 1.1 and 1.5 GB of memory, most of it in MariaDB, Apache and FreePBX's Node.js services.

Before you start

You need:

• a fresh Melonslab server with Debian 12 and nothing else installed. FreePBX 17 supports only Debian 12, and its installer stops on Debian 13. You choose Debian 12 when you order the server, or when you reinstall it in the client area;
• a name for it, such as pbx.example.com, with an A record and an AAAA record pointing at the server;
• the public IPv4 address you manage the server from, such as your office's address. The firewall in step 4 only lets that address reach SSH and the web interface. curl -4 ifconfig.me on your own computer shows it.

Set up SSH keys and automatic security updates as in steps 1 to 3 of the security guide, and skip its step 4: FreePBX has its own firewall, which manages iptables itself.

The examples use pbx.example.com, 203.0.113.10 for the server and 198.51.100.7 for your own address. Replace them throughout.

1. Prepare the server

FreePBX uses the server's name for its certificate. As root:

hostnamectl set-hostname pbx.example.com
sed -i "s/^127\.0\.1\.1.*/127.0.1.1 pbx.example.com pbx/" /etc/hosts
timedatectl set-timezone Europe/Stockholm
apt update
apt full-upgrade -y

If the upgrade installed a new kernel, restart the server before you go on, with systemctl reboot.

2. Install FreePBX

This is Sangoma's own installer, as described in its README:

wget https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh -O /tmp/sng_freepbx_debian_install.sh
bash /tmp/sng_freepbx_debian_install.sh

It took about 30 minutes on our test server and finishes with Finished FreePBX 17 installation process and a notice that the machine is not activated. The log is in /var/log/pbx/.

The installer also holds FreePBX's own packages, so apt upgrade leaves them alone, and blocks packages from Debian 13, so the server cannot be upgraded to a Debian release FreePBX does not support.

When it finishes, nothing is protected yet: the firewall is off, and whoever opens the web interface first creates the admin account. Do step 3 straight away.

3. Create the admin account

Open http://203.0.113.10/admin and fill in Initial Setup:

• Username, Password and Confirm Password for the admin account.
• Notifications Email address, where FreePBX sends notices about updates and security.
• System Identifier, a name for the server, such as pbx.example.com.
• Under System Updates, Automatic Module Updates is Enabled by default. Keep it, and pick a day and time under Check for Updates every.

Choose Setup System, then FreePBX Administration, and log in.

FreePBX now shows a series of windows:

• Would you like to activate your new system now? Choose Skip. Activation is optional; step 8 explains what it involves.
• Adverts for Sangoma's own products: PBXact Cloud, Sipstation, Soft clients, Sangoma Phones and Reseller Program. Choose Skip on each.
• Please Select the default locales of the PBX. For Swedish prompts, choose Swedish under Sound Prompts Language, then Submit.

The next window is Sangoma Smart Firewall is now enabled! Stop there, and do step 4 over SSH before you choose Continue.

4. Switch on the firewall without locking yourself out

The wizard asks if it should trust the computer you are using. In our test, answering Yes locked us out: from that moment SSH and the web interface refused every new connection, until the firewall was switched off from the console. The trust step loads FreePBX's rules, which drop everything not allowed, before your address is added, and nothing adds it until the firewall service starts.

So trust your address and start the firewall yourself, in one command, over SSH:

fwconsole firewall trust 198.51.100.7 && fwconsole firewall start

Your SSH session stays open. fwconsole firewall list trusted shows the address. Then, in the browser, reload the page and go through the wizard. It no longer asks about trusting your computer:

• Continue, then Next.
• Enable Responsive Firewall? Choose Yes. Phones and apps from any address can then register, and each one is let in once it has logged in successfully.
• Automatically configure Asterisk IP Settings? Choose Yes. FreePBX sets the server's public address and local network for SIP.
• SIPStation Free Trial: choose Not Now.

The firewall now works like this:

• Your trusted address reaches everything: SSH, the web interface on ports 80 and 443, and the rest.
• Everyone else only reaches SIP on UDP port 5060 and sound (RTP) on UDP ports 10000 to 20000. Connections to SSH and the web interface time out.
• A phone that has registered is also let in to the User Control Panel (UCP), where users read voicemail. Addresses that send too many requests are blocked.

The same rules apply to IPv6. Only the IPv4 address you trusted is trusted, so the rules also block SSH and the web interface over IPv6. We checked the IPv6 rules and HTTPS over IPv6 from the server itself, not from another IPv6 network. Asterisk listens for SIP on IPv4 only, so phones connect over IPv4.

If your own address changes, for example at home, you are locked out of SSH and the web interface. Log in on the console in the client area and trust the new address, as above.

After a reboot, the firewall waits until the server has been running for 5 minutes before it loads its rules. Until then, it lets everything through.

Intrusion detection is fail2ban, which the installer set up. It bans an address for 30 minutes after 5 failed SIP or web logins within 10 minutes, or 3 failed SSH logins. Its settings are on Connectivity, Firewall, under Intrusion Detection.

5. Get a certificate

The firewall lets Let's Encrypt reach port 80 by itself. In FreePBX, open Admin, then Certificate Management:

• Choose New Certificate, then Generate Let's Encrypt Certificate.
• Certificate Host Name already shows pbx.example.com. Enter your email address under Owners Email, choose Sweden as Country and your county as State.
• Choose Generate Certificate. The page shows LetsEncrypt Generation Success!.

Make it the default certificate, so the rest of FreePBX uses it too:

fwconsole certificates --default=pbx.example.com

The web server still uses its own certificate. The free version of System Admin, where FreePBX sets the web server's certificate, only works on activated servers, so point the web server at the certificate yourself:

sed -i -e "s|^\(\s*SSLCertificateFile\s\+\).*|\1/etc/asterisk/keys/pbx.example.com-fullchain.crt|" \
  -e "s|^\(\s*SSLCertificateKeyFile\s\+\).*|\1/etc/asterisk/keys/pbx.example.com.key|" \
  /etc/apache2/sites-available/default-ssl.conf
echo "30 0 * * * root systemctl reload apache2" > /etc/cron.d/reload-apache-cert
apachectl configtest && systemctl reload apache2

FreePBX checks its certificates every night at 00:16 and renews them when needed. The file in /etc/cron.d reloads the web server every night after that, so it picks up a renewed certificate. We saw the certificate issued, but did not wait for a renewal.

From now on, open https://pbx.example.com/admin. FreePBX also still answers on plain HTTP, without sending you on to HTTPS, so use the https:// address.

Set FreePBX's own time zone as well, under Settings, Advanced Settings, PHP Timezone, or with:

fwconsole setting PHPTIMEZONE Europe/Stockholm

It starts as UTC. A restore (step 9) sets the server's time zone from this setting, so without it, the server switches to UTC after a restore.

6. Add extensions

Open Connectivity, then Extensions. Choose Add Extension, then Add New SIP chan_pjsip Extension:

• User Extension: the number, such as 101.
• Display Name: the person's name.
• Secret: FreePBX fills in a long random password. Keep it; it is what the phone logs in with.

Choose Submit, then the red Apply Config button at the top. FreePBX only writes the new configuration for Asterisk when you apply it. Repeat for each extension, such as 102.

In the phone or the app, use:

Call 102 from 101 to try it. We tested with baresip, a SIP client for the command line, on a computer behind NAT on another network. Both extensions registered, and the call carried sound both ways through the server.

7. See what the firewall is doing

On Connectivity, Firewall, the Status tab shows Registered Endpoints, the addresses the Responsive Firewall has let in, and Blocked Hosts. From the command line:

fwconsole firewall f2bstatus
fail2ban-client status asterisk-iptables

Failed SIP logins are logged in /var/log/asterisk/fail2ban. On our test server, the first scanners arrived within two hours and tried common extension numbers. Because every extension has a long random secret, their attempts fail.

8. Commercial modules and what FreePBX sends to Sangoma

FreePBX itself is open source, but the installer also installs Sangoma's commercial modules: 35 of the 114 modules on our test server, such as System Admin, Endpoint Manager and SIPStation. Their code is encrypted with ionCube, so you cannot read what they do. The firewall depends on the commercial System Admin module, which is why this guide keeps them. The installer's --opensourceonly option removes them, and the firewall with them.

Activation registers the server with Sangoma and is needed to buy commercial modules or support. It asks for an email address and a password for a Sangoma portal account, and a name, and optionally phone numbers, a postal address and a business name. Everything in this guide works without it.

Without activation, FreePBX still contacts Sangoma:

• Every time it checks for module updates, it sends an install ID, a hashed machine ID, the versions of FreePBX, Asterisk and PHP, the list of installed modules and the number of users.
• The admin pages load Google Analytics, and send the FreePBX, Asterisk and PHP versions as you move around. On an activated server, they also send its deployment ID. Switch it off:

fwconsole setting BROWSER_STATS 0

After that, no more events were sent, but the pages still load Google's script from www.googletagmanager.com. The dashboard also fetches news from freepbx.org and asterisk.org.

The VoIPInnovations module is for a US trunk provider. When we restored a backup (step 9), it added seven "VoipInnovations Cloud Network" addresses to the firewall's Internal zone, which can reach SSH and the web interface. If you do not use VoIPInnovations, remove the module:

fwconsole ma remove voipinnovations

A restore after that did not add them again. fwconsole firewall list internal shows what is in the zone.

9. Back up

Open Admin, then Backup & Restore, and choose Add Backup:

• Enter a Backup Name, such as nightly.
• Under Storage Location, choose Local backup storage.
• Under Schedule and Maintenance, set Enabled to Yes, and Every to Day, with a time such as 03:00.
• Choose Save. The play button next to the backup runs it straight away.

The backup took about a minute and was 71 MB, most of it data for Endpoint Manager and music on hold. It is saved in /var/spool/asterisk/backup. It holds everything, including the extensions' secrets and the certificate's private key, and FreePBX makes it readable for every user on the server. Close the folder:

chmod 700 /var/spool/asterisk/backup

A backup that stays on the server does not help if the server is lost, so copy the files to another machine, for example with scp, and keep them safe.

To restore, open the Restore tab, choose the play button next to the backup under Restore from local cache, and Ok. A backup from another server can be uploaded there first. The restore took about 5 minutes on our test server.

10. Updates

With Automatic Module Updates on from step 3, FreePBX updates its own modules every week. To update now:

fwconsole ma upgradeall

The automatic security updates from the security guide install Debian's own updates. Asterisk and FreePBX's own packages come from Sangoma's package repository, which the automatic security updates do not use, and the installer holds FreePBX and Node.js, so they only change when you update them yourself. Do not upgrade the server to Debian 13 before Sangoma supports it.

Troubleshooting

You cannot reach SSH or the web interface after switching on the firewall. Your address is not trusted, or it has changed. Log in on the console in the client area as root, and run fwconsole firewall trust 198.51.100.7 && fwconsole firewall start with your current address. To switch the firewall off completely, run fwconsole firewall disable.

FreePBX asks you to activate the server. Choose Skip. Activation is optional (step 8).

The browser warns about the certificate. The web server is still using its own certificate. Do the sed command in step 5, and open the https://pbx.example.com address, not the IP address.

A phone registers but the call has no sound. Check that step 4's Automatically configure Asterisk IP Settings? was answered Yes. Under Settings, Asterisk SIP Settings, External Address must be the server's public IPv4 address.

fwconsole fails with "Permission denied" when writing a file. It runs as the asterisk user, which cannot write to /root. Give it a path such as /tmp instead.