external/iiab
1
0
Fork 0
mirror of https://github.com/iiab/iiab.git synced 2025-02-13 03:32:12 +00:00
Code Issues Releases Wiki Activity

Cleaner pbx/README.adoc

Browse source
This commit is contained in:
A Holt 2021-08-13 13:23:45 -04:00 committed by GitHub
parent d078dd2082
commit b20f359849
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 121 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

191
roles/pbx/README.adoc
View file

@ -1,153 +1,204 @@
== PBX README
This "pbx" playbook adds https://asterisk.org/[Asterisk] and https://freepbx.org/[FreePBX] to Internet-in-a-Box (IIAB) for VoIP and SIP functionality e.g. for rural telephony.
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.
The initial release (for IIAB 6.7 in February 2019) supported Ubuntu 18.04, Debian 9 "Stretch" — and experimentally, Raspberry Pi: https://github.com/iiab/iiab/issues/1467[#1467]
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"].
_2021-08-02 GOOD NEWS: IIAB has upgraded from Asterisk 16.x (released 2018-10-09) to 18.x (released 2020-10-20, https://wiki.asterisk.org/wiki/display/AST/Asterisk+18+Documentation[docs]): https://github.com/iiab/iiab/pull/2896[PR #2896]_
_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!_
_2021-08-02 WORK IN PROGRESS: The latest versions of Ubuntu (20.04, 20.10, 21.04), Debian 11 "Bullseye" and the imminent Raspberry Pi OS 11 "Bullseye" all include PHP 7.4 — which does not work with FreePBX 15 — so IIAB is making the transition to https://www.freepbx.org/freepbx-16-beta-is-here/[FreePBX 16 Beta^] which emerged on 2021-06-21: https://github.com/iiab/iiab/pull/2899[PR #2899]_
_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]).
_PLEASE UNDERSTAND THIS MEANS THAT: IIAB no longer supports FreePBX 15 (i.e. Linux distros with PHP <= 7.3, e.g. on Raspberry Pi OS 10 "Buster"). Thank you for your understanding, as we look to the future together!_
_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?
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.
=== What Asterisk & FreePBX do
FreePBX is a web-based open source GUI (graphical user interface) that controls and manages Asterisk (PBX), the open source communication server.
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.
=== Using it
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:
Prior to using IIAB, make sure 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] contains:
----
pbx_install: True
pbx_enabled: True
----
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
----
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:
You have an option of using an Apache (default) or NGINX webserver. To use nginx, add the following line to 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/7.4/apache2/php.ini` 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] — much like other IIAB Apps that use:
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
----
After installing PBX as part of IIAB, please visit http://box.lan:83/freepbx and proceed with initial configuration (no login/password is required initially — you will be asked to set this up).
To verify the FreePBX service is running, you can run this at the command-line:
You can monitor the FreePBX service with command:
----
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:
=== Steps to setup a basic working FreePBX configuration with a PJSIP extension
----
asterisk_chan_dongle: True
----
==== Initial configuration
// 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!)
After installing PBX as part of IIAB, please visit http://box.lan:83/freepbx on your browser and proceed with initial configuration. You will be asked to setup your username and password the first time you login which will be used in future to login to the FreePBX configuration screen. Once you login, select the first option 'FreePBX Administrator'.
==== Change the default Asterisk password
=== Try it out with an Android or iPhone softphone (SIP) app
// SIP Set up a basic working FreePBX configuration with a PJSIP extension
Go to Settings >> Asterisk settings. Click on _Submit_ button below and then click _Apply config_ that'll appear in red on the top right side of the web page.
==== 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 >> Under NAT settings, clicking "Detect Network Settings" will populate your external IP Under Local networks, enter your local IP settings in the form of IP/CIDR or IP/NETMASK such as, `192.168.0.0/24` or `192.168.0.0/255.255.255.0`
* Click on _Submit_ button below and then click _Apply config_ that'll appear on the top right side of the web page.
* 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 to enable you to make calls within your network
==== Create SIP phone extensions, so you can make calls
* Go to Applications >> Extensions >> Add Extension >> New chan_pjsip extension, and enter the following:
* Extension - _301_
* Display name - _John Doe_
* Secret - _strong password_
* Click on _Submit_ button on the bottom of the page and then click _Apply config_ that'll appear in red on the top right side of the web page.
* Using the same steps, you could create more extensions for other users.
* 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.jpg[]
image::files/add_extn_01_top.jpg[]
+
image::files/add_extn_02.jpg[]
==== Register the extension on your smartphone or laptop
==== Register the extension, on your smartphone or laptop
You can now register these extensions using a softphone app on your smartphone. For this example we will use the Linphone app on an Android phone. Once you open the app, follow the steps below:
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 to _Internet in a Box_ WiFi on your smartphone or laptop
* Select option _USE SIP ACCOUNT_
* Enter the same details that you set in freepbx web console: _Username_ is the same as _Extension_, _Password_ is the same as _Secret_ and _Domain_ is your asterisk server IP address
* Select _UDP_ option under _Transport_
* Click on Login
* 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[]
image::files/linphone_setup.jpg[width='33%']
* If connection is successful, you will see _connected_ with a green circle besides it on the next screen
* If the connection is successful, you will see a green circle next to *Connected* on this next screen:
+
image::files/linphone_connected.jpg[]
* If you have created more than one extension, make a call to another extension. You will see activity on the applet at the right side of your FreePBX Dashboard. Connection details may also be seen under asterisk logs at: '/var/logs/asterisk/full'
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
* sudo asterisk -rvvv
* The number of v's denote the verbosity level. In this case it is level 3
* If asterisk is running, it'll successfully take you to the asterisk console
. Check if Asterisk is up and running:
. If you see a _Asterisk is not connected_ in red on the FreePBX web console, check if asterisk is running using this command `systemctl status asterisk` on the terminal. Output should show the status as active(running). If not running, please restart asterisk using the command `sudo fwconsole restart`
* 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 a _fwconsole read_ error when you save settings, execute the command `sudo fwconsole chown` followed by `sudo fwconsole reload` on your terminal
. 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`
=== Some useful Asterisk commands and information
. Check all log files carefully, within this directory:
. `sudo asterisk -rvvvv`
- To reach asterisk CLI.
- Note: The number of v's denote the verbosity level. In this case, it is 4
/var/log/asterisk/
. `asterisk -rx "pjsip show endpoints"`
- This helps execute a command outside of the CLI, for use in a script
. If you see an _fwconsole read_ error when you save settings, try to run Linux command `sudo fwconsole chown` followed by `sudo fwconsole reload`
. `core show help`
- To see all available asterisk commands
=== Some useful Asterisk commands
. `pjsip show [tab]` or `pjsip show ?`
- To see all commands that start with `pjsip show`. You may try this with any command to see how to use it.
. To reach Asterisk's own CLI (command-line interface)
=== Additional information for using FreePBX
* Run Linux command: `sudo asterisk -rvvvv`
* Note: The number of v's denote the verbosity level. In this case, it is 4.
. If you forget your FreePBX password, you could bypass it using the command `sudo fwconsole <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
. 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.
. 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, you need to install _User Control Panel_ from Admin >> Module Admin >> Check online
. User Control Panel
=== Raspberry Pi known issues
* 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*.
+++<del>+++ 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+.
. Try FreePBX's commands like the following, at the Linux command-line:
+++<del>+++ 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]
* fwconsole list
* fwconsole -h
* fwconsole restart
* fwconsole ma list
* fwconsole ma -h
* fwconsole ma showupgrades
* fwconsole ma upgradeall
=== Raspberry Pi Zero W Warning
////
=== 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 "pbx" playbook was heavily 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!
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!