FreePBX is a powerful telephone PBX management platform that offers a range of functions, flexibility in customization, and rich integration options. Thanks to the web interface, configuration and management of the system becomes intuitive even for people without specialist knowledge in the field of telecommunications.
We will show you how to install it on the stable, secure and widely used free Debian operating system distribution. We will also use an excellent PBX engine, which ensures not only reliability, but also modern functions in line with the latest VoIP standards. Of course, this also includes free Asterisk.
Table of Contents
1) Preparing the environment
To install Debian, I recommend using a virtual machine created on Proxmox. If you haven’t used this virtualization environment yet, visit our blog and try install and configure proxmox yourself . In another post we describe how to install an example Linux in such an environment. I also encourage you to read the description of installing Asterisk 20 on Debian 12 and to pay attention to how to solve a possible problem with libasteriskssl or libasteriskpj
After the basic installation of the operating system, it is good practice to upgrade and update it. This allows us to be sure that we are using the latest versions of updates and fixes. Thanks to this, we increase the level of security and reliability of our environment.
apt update
apt upgrade
After a standard installation of Debian, we already have useful tools such as
nano, wget and tar in the package. We will also install the curl package for our needs.
apt install curl
To store installation packages, I use a dedicated location, which is the
/usr/src directory, where I also download the appropriate version of Asterisk and unpack it. Although we could download the latest version 20, on the FreePBX website we can see that it is not still officially supported. I will get rid of the zipped file and go to the directory where I will have access to the basic installer.
cd /usr/src/
wget https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-18-current.tar.gz
tar -zxvf asterisk-18-current.tar.gz
rm asterisk-18-current.tar.gz
cd asterisk-18.*
2) Asterisk installation
First, we will install the necessary dependencies and components required by Asterisk. This will be made easier by the script attached to the installer, which we will now run. When the window for entering the country code in which we will use our system appears, enter 48 (for Poland)
contrib/scripts/install_prereq install
I recommend running another prepared script that will then allow you to handle recordings in mp3 format.
contrib/scripts/get_mp3_source.sh
The next necessary step is to configure the basic installer and prepare appropriate files that will adapt Asterisk to our machine and operating system.
./configure
Correct completion of the configurator will result in displaying the Asterisk logo similar to the one below.
Before compiling the software for
FreePBX, we will add the required components. The following command will give us graphical access to the menu in which, firstly, we will add support for the mp3 format and a channel supporting communication using the H.323 protocol (chan_ooh323)
make menuselect
Secondly, in the Applications menu, you need to add the app_macro application and thirdly, add a few system music packages. (Core Sound Packages: EN-WAV, EN-ULAW, EN-ALAW, EN-GSM, EN-G729, EN-G722, EN-SLN16; Music On Hold File Packages: OPSOUND-WAV, OPSOUND-ULAW, OPSOUND-ALAW, OPSOUND-GSM, OPSOUND-G729, OPSOUND-G722, OPSOUND-SLN16; Extras Sound Packages: EN-WAV, EN-ULAW, EN-ALAW, EN-GSM, EN-G729, EN-G722, EN-SLN16). Adding system music packages can be limited to one or two codecs. The more of them we load, the more we will save system resources when we use many different sound files.
HINT
Instead of using the graphical interface and manually selecting additional modules and music, you can execute the following command:
make menuselect.makeopts \
&& menuselect/menuselect --enable CORE-SOUNDS-EN-WAV CORE-SOUNDS-EN-ULAW CORE-SOUNDS-EN-ALAW CORE-SOUNDS-EN-GSM CORE-SOUNDS-EN-G729 CORE-SOUNDS-EN-G722 CORE-SOUNDS-EN-SLN16 \
&& menuselect/menuselect --enable MOH-OPSOUND-WAV MOH-OPSOUND-ULAW MOH-OPSOUND-ALAW MOH-OPSOUND-GSM MOH-OPSOUND-G729 MOH-OPSOUND-G722 MOH-OPSOUND-SLN16 \
&& menuselect/menuselect --enable EXTRA-SOUNDS-EN-WAV EXTRA-SOUNDS-EN-ULAW EXTRA-SOUNDS-EN-ALAW EXTRA-SOUNDS-EN-GSM EXTRA-SOUNDS-EN-G729 EXTRA-SOUNDS-EN-G722 EXTRA-SOUNDS-EN-SLN16 \
&& menuselect/menuselect --disable BUILD_NATIVE --enable format_mp3 --enable chan_ooh323 --enable app_macro
Nevertheless, make sure that each of these options is selected by calling make menuselect
The next commands will compile Asterisk, install it, and generate sample configuration files and startup files.
make
make install
make samples
make config
Optionally, you can execute one more command at the end that helps the operating system configure and manage shared libraries. It will search the standard locations where the system stores shared libraries and update information about them in the database so that the system can find them more efficiently when executing programs.
ldconfig
3) Asterisk configuration
Now we will configure Asterisks for a specific solution, which is the FreePBX telephone platform.
First, we will create a dedicated group and user
asterisk. Its home directory will be /var/lib/asterisk
groupadd asterisk
useradd -r -d /var/lib/asterisk -g asterisk asterisk
Then we will add the user to the
audio and dialout groups. The audio group has permissions related to audio support, while the dialout group has permissions related to access to connection devices (for example, modems). Adding the asterisk user to these groups is necessary to allow them access to certain system functions related to audio and calling.
usermod -aG audio,dialout asterisk
We will also set the asterisk user and asterisk group as the owner of the directories used by the phone system.
chown -R asterisk:asterisk /etc/asterisk
chown -R asterisk:asterisk /var/{lib,log,spool}/asterisk
chown -R asterisk:asterisk /usr/lib/asterisk
In two asterisk configuration files, we will set our asterisk user as the default user under which the asterisk system itself will be run. You should uncomment the following lines to the state shown below:
nano /etc/default/asterisk
AST_USER="asterisk"
AST_GROUP="asterisk"
nano /etc/asterisk/asterisk.conf
runuser = asterisk
rungroup = asterisk
At the end of this part, we will start Asterisk, add it to autostart and test log in to the console.
systemctl restart asterisk
systemctl enable asterisk
asterisk -rvvv
It is not an important problem that needs to be addressed now, if after starting Asterisk, we see some warnings and errors related to module loading, similar to the ones below.
In the
modules.conf file you can disable the autoload = yes option and load modules manually.
nano /etc/asterisk/modules.conf
You can also deselect unnecessary modules during the
make menuselect command (point 2), for example those visible in the screenshot above. 4) Database installation and configuration
FreePBX requires a database to function properly. We will install an instance of the MariaDB database.
apt install mariadb-server mariadb-client
Then we will run a script that secures our database environment. It will require some interactions with us. It will ask us for a password, which we do not enter because it is empty (click Enter). We answer n (no) to the next question and then Y (yes) to set the root password and enter it in the next step. Let’s make sure it’s really safe and we remember it. We agree to block anonymous users and remote access. We delete the test database and reload the permissions.
/usr/bin/mysql_secure_installation
The following command will show us whether the database has been installed correctly by showing us its version.
mysql -V
5) Node.js installation
Node.js is another component that FreePBX requires to properly interact with the website. The installer requires little interaction with the user, so after running it, click Y. We also install the package manager for the Node.js environment, i.e. npm. Without it, our website would work, but we would get a lot of errors and we would not be able to reload the FreePBX configuration, for example.
apt install nodejs npm
The following command will show us whether
Node.js has been installed correctly by showing us its version.
node -v
6) Apache installation and configuration
Installing
apache is necessary for FreePBX to work. This installer also requires little interaction with the administrator, so at some point we just click Y
apt install apache2
It is good practice to save the original configuration files before modifying them. So we will create a copy of the
apache2.conf file and look at the place we are most interested in, shown in the clipping below.
cp /etc/apache2/apache2.conf /etc/apache2/apache2.conf_backup
nano /etc/apache2/apache2.conf
It is worth noting that we need to change the user information in another file that stores variable values:
/etc/apache2/envvars . So let’s make the necessary changes there. Enter our user asterisk. The relevant fragment of this file will look like this:
cp /etc/apache2/envvars /etc/apache2/envvars.backup
nano /etc/apache2/envvars
export APACHE_RUN_USER=asterisk
export APACHE_RUN_GROUP=asterisk
In the main configuration file
/etc/apache2/apache2.conf we need to replace all occurrences of AllowOverride None with AllowOverride All . This will enable FreePBX to flexibly configure the website. You can do this by editing the file manually, but it is more elegant to use the sed command, which I encourage you to do.
sed -i 's/AllowOverride None/AllowOverride All/' /etc/apache2/apache2.conf
At the end of this part, we need to delete the
index.html file
rm -f /var/www/html/index.html
7) PHP installation
PHP is already installed on our system, but in version 8.x. Unfortunately, FreePBX does not support this version yet, so we will have to switch to the version supported by our target application, i.e. 7.4. This obviously carries some security risks, but there’s nothing we can do about it. We will create a new repository file
php.list for the older version of php and fill it with the following content. Additionally, we will check the code name of our Debian system (in our case it is bookworm)
lsb_release -sc
nano /etc/apt/sources.list.d/php.list
deb https://packages.sury.org bookworm main
HINT
You’ve probably noticed how much I like elegant and condensed commands, so here too, creating a repository can be done with one command, here it is:
sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
For the repository to work properly, we also need the appropriate GPG key, so we will download it and add it to our system using the apt-key tool. Of course, all in one command.
wget -qO - https://packages.sury.org/php/apt.gpg | apt-key add -
After executing this command, we will receive a warning like:
apt-key is deprecated We can ignore it. We will not use the new key management method in this case. ATTENTION
If we immediately try to install an older version of php, we will receive an error saying that this version is unavailable. We must remember to first update the list of packages available in our system.
apt update
Now we can install the older version of php and the necessary modules and packages that are required by the developers of FreePBX.
apt install php7.4
apt install libapache2-mod-php7.4 php7.4-{cgi,common,curl,mbstring,gd,mysql,gettext,bcmath,zip,xml,imap,json,snmp,fpm}
We still need to change one entry in two configuration files responsible for the size of the downloaded files.
sed -i 's/\(^upload_max_filesize = \).*/\120M/' /etc/php/7.4/apache2/php.ini
sed -i 's/\(^upload_max_filesize = \).*/\120M/' /etc/php/7.4/cli/php.ini
Finally, we need to enable the Apache module called
rewrite. This module allows you to use the URL rewriting function in the Apache server. For everything to work, we need to restart the Apache service.
a2enmod rewrite
systemctl restart apache2
8) FreePBX installation
It was finally time to install FreePBX itself. We will download and unpack the software from the manufacturer’s website to our sources directory, i.e.
/usr/src
cd /usr/src
wget https://mirror.freepbx.org/modules/packages/freepbx/freepbx-16.0-latest.tgz
tar -zxvf freepbx-16.0-latest.tgz
rm freepbx-16.0-latest.tgz
Now let’s go to the directory with the installation files and check if our FreePBX can communicate with Asterisk.
cd freepbx/
./start_asterisk start
Communication is correct, so we can run the basic installer. I hope that the database password you enter will be more complex than the one I used here for testing purposes for this article. (we set them in point 4)
./install -n --dbuser root --dbpass "SQLPa$$w0rd"
Way to go! FreePBX has been installed! Let’s perform a preventive reboot of the entire machine.
reboot
9) FreePBX configuration
Now we can log in to the FreePBX graphical interface via a web browser. Go to the website by entering the IP address of your asterisk system.
http://<ip address>/admin/config.php
Complete details such as administrator name and password, email for notifications and system ID as you wish. Click
Setup System 
On the next page, click
FreePBX Administration and enter username and password. 
On the next page, select the voice announcement language and system language.
After this short initial configuration, we have a ready-made administration panel. Let’s click
Apply Config to save our configuration files to Asterisk. The reloading message will disappear after this operation is performed. As you can see, we have the System Overview tab here, where we can find potential problems and warnings. This time there is information about the missing SOX module. 
In this case, we can simply go back to our ssh session and install this missing module.
apt install sox
If you are still missing some applications or connections, select
Menu Admin -> Module Admin. There, click Check Online and then Download All and Process. You will see a window showing the installation process. 
Click
Return. You will return to the main panel. There, confirm the performed operations with the Apply Settings button. From now on, you can enjoy a fully equipped and functional telephone exchange environment. 
If you would like tomonitor everything that is happening on your PBX, try our proprietary software VOIPERO
Installation and configuration takes a few minutes and the system is currently availabletotally free
Read what our VOIPERO system can do in terms of live monitoring and reporting of Asterisk-based VoIP systems.
