iiab/roles/pbx/README.adoc

== PBX README

IIAB can install https://asterisk.org/[Asterisk] and https://freepbx.org/[FreePBX] to Internet-in-a-Box (IIAB) for Voice over IP (VoIP) calls using regular Android and iPhone softphone (SIP) apps, e.g. for low-cost and rural telephony.

As of August 2021, IIAB installs https://wiki.asterisk.org/wiki/display/AST/Asterisk+18+Documentation[Asterisk 18] and https://www.freepbx.org/freepbx-16-beta-is-here/[FreePBX 16 Beta], as required by the latest PHP 7.4 Linux OS's (https://github.com/iiab/iiab/pull/2899[PR #2899]).  Please consider installing this on https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems[Ubuntu 20.04+, Debian 11 — or the imminent Raspberry Pi OS 11 "Bullseye"].

_PLEASE UNDERSTAND THIS MEANS THAT: IIAB no longer supports FreePBX 15 (Linux with PHP < 7.4, e.g. Raspberry Pi OS 10 "Buster").  Thank you for your understanding, as we look to the future together!_

_Upcoming:_ IIAB will consider supporting Asterisk 19, on or around its 2021-09-28 expected release date (https://github.com/iiab/iiab/issues/2934[#2934]).

_Historical:_ Back in February 2019, IIAB had installed Asterisk 16 and FreePBX 15, e.g. for Ubuntu 18.04, Debian 9 "Stretch" and experimentally, Raspberry Pi (https://github.com/iiab/iiab/issues/1467[#1467]).


=== What Asterisk & FreePBX do

https://en.wikipedia.org/wiki/Asterisk_(PBX)[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.

https://en.wikipedia.org/wiki/FreePBX[FreePBX] is a web-based open source GUI (graphical user interface) that controls and manages Asterisk (PBX), the open source communications server.


=== Install it

Make sure your IIAB configuration file (http://wiki.laptop.org/go/IIAB/FAQ#What_is_local_vars.yml_and_how_do_I_customize_it.3F[/etc/iiab/local_vars.yml]) contains:

----
pbx_install: True
pbx_enabled: True
----

You have the option of using the Apache (default) or NGINX web server.  To use NGINX, include this line in your http://wiki.laptop.org/go/IIAB/FAQ#What_is_local_vars.yml_and_how_do_I_customize_it.3F[/etc/iiab/local_vars.yml] file:

----
pbx_try_nginx: True
----

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 https://github.com/iiab/iiab/blob/master/roles/www_options/tasks/main.yml#L88-L131[/opt/iiab/iiab/roles/www_options/tasks/main.yml] &mdash; some of which happens automatically if you've also set:

----
nginx_high_php_limits: True
----

To verify the FreePBX service is running, you can run this at the command-line:

----
systemctl status freepbx
----

Optionally, you may want to enable https://github.com/wdoekes/asterisk-chan-dongle[chan_dongle], which is a channel driver for Huawei UMTS cards allowing regular voice calls over GSM. You will need to configure a dongle post-install, for it to be recognized properly:

----
asterisk_chan_dongle: True
----

// After installing PBX as part of IIAB, please visit http://box.lan:83/freepbx (Apache) or http://box.lan/freepbx (NGINX) and proceed with initial configuration (no login/password is required initially — you will be asked to set this up!)


=== Try it out with an Android or iPhone softphone (SIP) app
// SIP Set up a basic working FreePBX configuration with a PJSIP extension

==== Initial Configuration

// After installing PBX as part of IIAB, please
Browse to http://box.lan:83/freepbx (Apache) or http://box.lan/freePBX (NGINX) and proceed with initial configuration (no login/password is required initially — you will be asked to set this up!)
// You will be asked to set up your username and password the first time you login, which will be used in future to log in for FreePBX configuration.

To log in, click the first option: *FreePBX Administration*

==== 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)
+
image::files/advanced_settings.jpg[]

==== Change Asterisk SIP 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)
+
image::files/asterisk_sip_settings.jpg[]

==== Create SIP phone extensions, so you can make calls

* Go to *Applications* > *Extensions* > *Add Extension* > *Add New SIP [chan_pjsip] Extension*, and enter an extension (local phone number) such as the following:
** *User Extension*: _301_
** *Display Name*: _John Doe_
** *Secret*: _strong password_
* Click *Submit* (bottom of page), then *Apply Config* (top of page)
* Using the same steps, create extensions for every user!
+
image::files/add_extn_01_top.jpg[]
+
image::files/add_extn_02.jpg[]

==== Register the extension, on your smartphone or laptop

You can now register the extensions using a softphone (SIP) app on your smartphone.  In this example we will use the https://en.wikipedia.org/wiki/Linphone[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 console website:
** *Username* is the same as _User Extension_
** *Password* is the same as _Secret_
** *Domain* is your IIAB server's IP address
* Select *UDP* under *Transport*
* Select *LOGIN*
+
image::files/linphone_setup.jpg[width='33%']

* If the connection is successful, you will see a green circle next to *Connected* on this next screen:
+
image::files/linphone_connected.jpg[width='33%']

* If you have created more than one extension, make a call to another extension.  You will see activity in the *FreePBX Statistics* applet on your http://box.lan:83/freebx (or http://box.lan/freebx) Dashboard.  Connection details may also be seen in the Asterisk logs at: `/var/logs/asterisk/full`


=== Troubleshooting

. 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).

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

. Check all log files carefully, within this directory:

  /var/log/asterisk/

. If you see an _fwconsole read_ error when you save settings, try to run Linux command `sudo fwconsole chown` followed by `sudo fwconsole reload`

=== Some useful Asterisk commands

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

  * Run Linux command: `sudo asterisk -rvvvv`
  * Note: The number of v's denote the verbosity level.  In this case, it is 4.

. To see all available Asterisk commands:

  * Run Asterix command: `core show help`

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

  * Run Asterix command: `pjsip show [tab]` or `pjsip show ?`
  * Try this with any command!

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

  * Run Linux command: `asterisk -rx "pjsip show endpoints"`


=== Additional FreePBX info

. If you forget your FreePBX password, you can bypass it using Linux command `sudo fwconsole unlock <Session ID>` and then refresh the 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:
+
image::files/pwdless_login.jpg[]

. 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.
+
image::files/password_change.jpg[]

. User Control Panel

  * If you'd like to allow users to manage some of their own settings and view their statistics, install the *User Control Panel* FreePBX module from *Admin* > *Module Admin* > *Check Online*.

. Try FreePBX's commands like the following, at the Linux command-line:

  * fwconsole list
  * fwconsole -h
  * fwconsole restart
  * fwconsole ma list
  * fwconsole ma -h
  * fwconsole ma showupgrades
  * fwconsole ma upgradeall


////
=== Raspberry Pi Known Issues

As of 2019-02-14, "systemctl restart freepbx" failed more than 50% of the time when run on a http://wiki.laptop.org/go/IIAB/FAQ#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F[BIG-sized] install of IIAB 6.7 on RPi 3 or RPi 3 B+.

It is possible that FreePBX restarts much more reliably when run on a MIN-sized install of IIAB?  Please http://wiki.laptop.org/go/IIAB/FAQ#What_are_the_best_places_for_community_support.3F[contact us] if you can assist here in any way: https://github.com/iiab/iiab/issues/1493[#1493]
////


=== Known Issues

If there's a bug or serious problem with IIAB, please do https://internet-in-a-box.org/pages/contributing.html[make contact] and post an issue here: https://github.com/iiab/iiab/issues

==== 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 (https://nodered.org/docs/hardware/raspberrypi#swapping-sd-cards[attempt!]) to https://github.com/iiab/iiab/blob/master/roles/nodejs/tasks/main.yml[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 https://github.com/iiab/iiab/issues/2082#issuecomment-569344617[#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. https://github.com/iiab/iiab/issues/1799[#1799]

Please also check the "Known Issues" at the bottom of https://github.com/iiab/iiab/wiki#our-evolution[IIAB's latest release notes].


=== Attribution

This https://github.com/iiab/iiab/tree/master/roles/pbx[pbx] playbook was originally inspired by Yannik Sembritzki's https://github.com/Yannik/ansible-role-asterisk[Asterisk] and FreePBX https://github.com/Yannik/ansible-role-freepbx[FreePBX] Ansible work, Thank You!