Internet-in-a-Box (IIAB) can install Asterisk and FreePBX for Voice over IP (VoIP) calls using regular Android and iPhone softphone (SIP) apps — e.g. for low-cost and rural telephony.

As of December 2024, IIAB supports Asterisk 22 and FreePBX 17 (announcement). A modern OS with PHP 8.x is required (PR #3675).

Asterisk is a software implementation of a private branch exchange (PBX). In conjunction with suitable telephony hardware interfaces and network applications, Asterisk is used to establish and control telephone calls between telecommunication endpoints, such as customary telephone sets, destinations on the public switched telephone network (PSTN), and devices or services on Voice over Internet Protocol (VoIP) networks. Its name comes from the asterisk (*) symbol for a signal used in dual-tone multi-frequency (DTMF) dialing.

FreePBX is a web-based open source GUI (graphical user interface) that controls and manages Asterisk (PBX), the open source communications server.

1. As you begin installing Internet-in-a-Box (IIAB) from download.iiab.io, it will prompt you:

   Edit /etc/iiab/local_vars.yml to customize your Internet-in-a-Box? [Y/n]

   Accept the challenge! Make sure your IIAB configuration file (/etc/iiab/local_vars.yml) contains:

   pbx_install: True
   pbx_enabled: True

   FreePBX can be used with either or both web servers — NGINX on port 80 (http://box/freepbx) and/or using the old approach with Apache on port 83 (http://box:83/freepbx).

   If you still want the older Apache approach, set this line in your /etc/iiab/local_vars.yml prior to installing IIAB:

   pbx_use_apache: True

   If you want to disable to new NGINX approach, set this line in your /etc/iiab/local_vars.yml:

   pbx_use_nginx: False

   If using PBX intensively, please adjust /etc/php/X.Y/apache2/php.ini, /etc/php/X.Y/cli/php.ini and/or /etc/php/X.Y/nginx/php.ini (where X.Y is typically 7.4) as outlined within /opt/iiab/iiab/roles/www_options/tasks/main.yml — some of which happens automatically if you also set:

   nginx_high_php_limits: True

   Optionally, you may want to enable chan_dongle, which is a channel driver for Huawei UMTS cards (e.g. 3G USB dongles) allowing regular voice calls over GSM mobile networks. You will need to configure a dongle post-install, for it to be recognized properly:

   asterisk_chan_dongle: True

2. Complete the installation, proceeding with the regular instructions (e.g. run sudo iiab, repeatedly if necessary).

3. After IIAB is installed with Asterisk and FreePBX, verify that the FreePBX service is running, by running this at the command-line:

   systemctl status freepbx

   If FreePBX is not running well, check the long-form output of journalctl -u freepbx and the Troubleshooting section further below.

1. Log in to FreePBX

   Browse to http://box/freepbx (NGINX) or http://box:83/freepbx (Apache), and proceed with initial configuration (no login/password is required initially — you will be asked to set this up!)

   To log in, click the first option: FreePBX Administration

   If you forgot your FreePBX password, see further below.

2. Change your Asterisk password, if you choose

   • Click Settings > Advanced Settings

     • In section Asterisk Manager, change your Asterisk Manager Password

   • Click Submit (bottom of page), then Apply Config (top of page)

     

3. Set Network NAT Settings

   • Go to Settings > Asterisk SIP settings

     • In section NAT Settings, click Detect Network Settings to populate your External Address and Local Networks.

     • Under Local Networks, you can also manually set an IP/CIDR (e.g. 192.168.0.0/24) or an IP/NETMASK (e.g. 192.168.0.0/255.255.255.0).

   • Click Submit (bottom of page), then Apply Config (top of page)

     

4. Create SIP phone extensions, so you can make calls

   • Go to Applications > Extensions > Add Extension > Add New SIP [chan_pjsip] Extension, and create a phone extension (local phone number) such as the following:

     • User Extension: 301

     • Display Name: John Doe

     • Secret: y0ur 0wn $tr0ng p4ssw0rd

   • Click Submit (bottom of page), then Apply Config (top of page)

   • Using the same steps, create extensions for every user!

     
     

5. Register the extension, on your smartphone or laptop

   You can now register the extension using a softphone (SIP) app on your smartphone or laptop. In this example we will use the Linphone app, on an Android phone. After you open the app, follow these steps:

   • Connect your smartphone or laptop to the Internet in a Box WiFi hotspot

   • Select USE SIP ACCOUNT

   • Enter those same details that you entered above into the FreePBX administration website:

     • Username is the same as above User Extension

     • Password is the same as above Secret

     • Domain is your IIAB server’s IP address

   • Select UDP under Transport

   • Select LOGIN

     

   • If the connection is successful, you will see a green circle next to Connected on this next screen:

     

   • If you’ve created more than one extension, make a call to another extension! If you’ve not yet made more than one extension, try calling an arbitrary extension, or try calling your own extension (your own phone number).

     Due to Linphone’s inability for phones to ring when the screen is locked, you can alternatively use a softphone (SIP) app on your smartphone or laptop called Wave Lite. In this example we will use the [https://wiki.zenitel.com/wiki/Grandstream_Wave_Lite_mobile_app], on an Android phone. After you open the app, follow these steps:

     • Connect your smartphone or laptop to the Internet in a Box WiFi hotspot

     • Go to Account Settings

     • Add new account

     • Select SIP ACCOUNT

       • Account name is your name, e.g. John Doe

       • Sip Server is your IIAB server’s IP address

       • SIP User ID is your extension number, e.g. 301

       • SIP Authentification ID is your extension number, e.g. 301

       • Password is the same as above Secret

       • *Confirm by clicking tick symbol ✓ (top right)

         

     • If the connection is successful, you will see a green circle next to your name [John Doe].

       

     • You should see activity in the FreePBX Statistics applet at http://box/freebx (or http://box:83/freebx) > Dashboard

     • Connection details may also be seen in the Asterisk logs at: /var/logs/asterisk/full

     • Please create a Privacy Policy against abusive surveillance, and explain it to the people in your community. Strongly consider giving them access to their own statistics with the User Control Panel summarized further below.

1. Try the script iiab-asterisk-test to:

   • Create two extensions 301 and 302, and configure a dialplan for routing calls (as specified in pjsip_custom.conf and extensions_custom.conf, located within /opt/iiab/iiab/roles/pbx/templates).

   • Make a test call to extension 1000 (that has no physical device associated with it) that plays some sound files.

   • After the script completes, it deletes the extensions and reverts file changes to restore asterisk to its original state. If you’d like your changes to persist, read the options below.

2. Usage:

   • sudo ./iiab-asterisk-test

     Default option - Executes the complete script and reverts file changes done during the test.

   • sudo ./iiab-asterisk-test retain

     Extensions created during the test are retained. Files are not reverted after the test.

     You may try making calls to extension 302 or 1000 after registering your softphone as mentioned above. The password for the extension is present in pjsip_custom.conf, feel free to change it before executing the script.

   • sudo ./iiab-asterisk-test revert

     Use this option if you executed the script using the retain option, but would like to have the changes reverted now. This will only revert the changes to the files and restart asterisk, no other actions are performed.

   • sudo ./iiab-asterisk-test restart

     Restarts asterisk, no other actions are performed

   • sudo ./iiab-asterisk-test testcall

     Makes a test call from Asterisk’s console to extension 1000, and confirms from the logs if the call was successful.

     Note: This will only work if you’ve created extension 1000 manually, or using FreePBX or using the retain option of this script

3. Read more about creating extensions and dialplans if you want to extend this script.

1. Check if Asterisk is up and running:

   • Run Linux command: sudo asterisk -rvvv

   • The number of v’s denotes the verbosity level. In this case, it is 3.

   • If Asterisk is running, it’ll take you to the Asterisk CLI (command-line interface).

2. If you see Asterisk is not connected in red within FreePBX’s web interface, check that Asterisk is running using Linux command sudo pgrep asterisk. You should see at least 2 different process numbers. If not, please restart Asterisk using Linux command: sudo fwconsole restart

3. Check all log files carefully, within this directory:

   /var/log/asterisk/

4. If you see an fwconsole read error when you save FreePBX settings, try to run these Linux commands:

   sudo fwconsole chown
   sudo fwconsole reload

1. To reach Asterisk’s own CLI (command-line interface)

   • Run Linux command: sudo asterisk -rvvvv

   • Note: The number of v’s denotes the verbosity level. In this case, it is 4.

2. To see all available Asterisk commands:

   • Run Asterix command: core show help

3. To see all commands that start with pjsip show:

   • Run Asterix command: pjsip show [tab] or pjsip show ?

   • Try this with any command!

4. To run an Asterisk command outside of Asterisk’s CLI, e.g. for use in a script:

   • Exit the Asterisk CLI, and try Linux commands like:

     asterisk -rx "core show version"
     asterisk -rx "pjsip show endpoints"
     asterisk -rx "cdr show status"

1. /etc/freepbx.conf allows you to override FreePBX’s stored settings if necessary.

   A better way however, is to use http://box/freepbx or http://box:83/freepbx > Settings > Advanced Settings to modify those stored settings — or equivalently, run Linux commands like:

   sudo fwconsole set -l                # Show all FreePBX settings' raw values
   sudo fwconsole set CHECKREFERER      # Show setting's value, in human-readable form
   sudo fwconsole set CHECKREFERER 0    # 0 means false (or set it to 1, to re-enable FreePBX's default)

2. Also try FreePBX commands like the following, at the Linux command-line:

   sudo fwconsole list                  # List commands
   sudo fwconsole -h
   sudo fwconsole restart
   sudo fwconsole ma list               # ma = Module Administration (e.g. shows ~16 default modules, of ~70 total)
   sudo fwconsole ma -h
   sudo fwconsole ma showupgrades
   sudo fwconsole ma upgradeall         # Upgrade your FreePBX modules (as normally happens Saturday 4-8AM)

3. User Control Panel

   • If you’d like to allow users more control over their own settings, and the ability to review their own statistics, install the User Control Panel FreePBX module from http://box/freepbx or http://box:83/freepbx > Admin > Module Admin > Check Online.

4. If you forget your FreePBX password, you can bypass it using Linux command sudo fwconsole unlock <Session ID> and then refresh your FreePBX web page:

   • To get the Session ID, press Ctrl + a which will highlight all the text on the page. The text highlighted in the middle of the page, is the Session ID:

     

   • Once you’ve logged in, change your password under Admin > Administrators. On the right side, you will see the list of available users. You can select the appropriate user and change the password:

     

Please also check the "Known Issues" at the bottom of IIAB’s latest release notes.

If there’s a bug or serious problem with IIAB, please do make contact and post an issue here: https://github.com/iiab/iiab/issues

1. Please see Asterisk’s Security Advisories: https://www.asterisk.org/downloads/security-advisories/

2. Apache’s /var/lib/php/asterisk_sessions/ directory might also be needed for NGINX?

   If not, the configuration of /var/lib/php/asterisk_sessions/ might be made conditional upon when: not pbx_use_apache

3. The installation of /etc/odbc.ini for CDR (Call Detail Records) database asteriskcdrdb might benefit from compiling the ODBC driver for aarch64, per https://mghadam.blogspot.com/2021/03/install-asterisk-18-freepbx-15-on.html ?

   See the output of asterisk -rx "cdr show status" as mentioned at #2938 and PR #2942.

4. Raspberry Pi Zero W Warning

   Node.js applications like Asterisk/FreePBX, Node-RED and Sugarizer won’t work on Raspberry Pi Zero W (ARMv6) if you installed Node.js while on RPi 3, 3 B+ (ARMv7) or RPi 4 (ARMv8). If necessary, run apt remove nodejs or apt purge nodejs then rm /etc/apt/sources.list.d/nodesource.list; apt update then (attempt!) to install Node.js on the Raspberry Pi Zero W itself (a better approach than "cd /opt/iiab/iiab; ./runrole nodejs" is to try apt install nodejs or try installing the tar file mentioned at #2082). You might also need apt install npm. Whatever versions of Node.js and npm you install, make sure /etc/iiab/iiab_state.yml contains the line nodejs_installed: True (add it if nec!) Finally, proceed to install Asterisk/FreePBX, Node-RED and/or Sugarizer. #1799

In February 2019, this roles/pbx IIAB Ansible playbook was originally inspired by Yannik Sembritzki’s Asterisk and FreePBX Ansible work from 2017-2019.

In August 2021 it was overhauled, with thanks to these 3 sources especially:

• "Official" recipe: https://wiki.freepbx.org/display/FOP/Installing+FreePBX+16+on+Debian+10.9

• Comprehensive & recent recipe for Raspberry Pi: https://mghadam.blogspot.com/2021/03/install-asterisk-18-freepbx-15-on.html

• Popular but dated recipe: https://computingforgeeks.com/how-to-install-asterisk-16-with-freepbx-15-on-ubuntu-debian/

In May 2022, installation of FreePBX was made more resilient in PR #3229 thanks to:

• Ron Raikes' routine to install FreePBX from GitHub: https://community.freepbx.org/t/asterisk-19-1-0-and-freepbx-install/81029/15

In 2024, see also the official:

• FreePBX 17 Installation Script (for Debian 12): https://github.com/FreePBX/sng_freepbx_debian_install

• FreePBX 17 Installation: https://sangomakb.atlassian.net/wiki/spaces/FP/pages/230326391/FreePBX+17+Installation

• Step By Step Debian 12 Installation: https://sangomakb.atlassian.net/wiki/spaces/FP/pages/295403538/Step+By+Step+Debian+12+Installation

Thank you to ALL who’ve contributed — including Lemuel D’Souza, Jerry Vonau, Adam Holt and Anish Mangal!