From 21a37e04a7fbadbb4f3dae77cc3d05601bb89353 Mon Sep 17 00:00:00 2001 From: A Holt Date: Fri, 13 Aug 2021 16:30:15 -0400 Subject: [PATCH] pbx/README.doc: Lint AsciiDoc syntax (1st attempt) + Known Issues + Attribution --- roles/pbx/README.adoc | 112 +++++++++++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 40 deletions(-) diff --git a/roles/pbx/README.adoc b/roles/pbx/README.adoc index 82a0a3f24..8f44d1c4c 100644 --- a/roles/pbx/README.adoc +++ b/roles/pbx/README.adoc @@ -79,8 +79,8 @@ image::files/advanced_settings.jpg[] * 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`). +** 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) + @@ -90,9 +90,9 @@ image::files/asterisk_sip_settings.jpg[] * 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_ +** *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! @@ -109,9 +109,9 @@ You can now register the extension using a softphone (SIP) app on your smartphon * 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 +** *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* @@ -124,51 +124,67 @@ image::files/linphone_connected.jpg[width='33%'] * 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). - ** You should see activity in the *FreePBX Statistics* applet at 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` - ** Please create a https://en.wikipedia.org/wiki/Privacy_policy[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 <<#UCP,User Control Panel>> explained further below. +** You should see activity in the *FreePBX Statistics* applet at 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` +** Please create a https://en.wikipedia.org/wiki/Privacy_policy[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 <<#UCP,User Control Panel>> explained further below. === 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). +* 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/ +---- - /var/log/asterisk/ - -. If you see an _fwconsole read_ error when you save FreePBX settings, try to run Linux command `sudo fwconsole chown` followed by `sudo fwconsole reload` +. If you see an _fwconsole read_ error when you save FreePBX settings, try to run these Linux commands: ++ +---- +sudo fwconsole chown +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 denotes the verbosity level. In this case, it is 4. +* Run Linux command: `sudo asterisk -rvvvv` +* Note: The number of v's denotes the verbosity level. In this case, it is 4. . To see all available Asterisk commands: - * Run Asterix command: `core show help` +* 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! +* 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"` +* Run Linux command: `asterisk -rx "pjsip show endpoints"` === Additional FreePBX info +. `/etc/freepbx.conf` allows you to override FreePBX settings if necessary. A better way however, is to use http://box.lan:83/freepbx or http://box.lan/freepbx > *Settings* > *Advanced Settings* — or equivalently, run Linux commands like: ++ +---- +sudo fwconsole set -l # View FreePBX settings +sudo fwconsole set -h # Show all 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. +---- + . If you forget your FreePBX password, you can bypass it using Linux command `sudo fwconsole unlock ` 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[] @@ -177,19 +193,21 @@ image::files/pwdless_login.jpg[] + image::files/password_change.jpg[] -. [[UCP]]https://wiki.freepbx.org/pages/viewpage.action?pageId=28180526[User Control Panel] +. [[UCP]]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*. + * If you'd like to allow users to manage some of their own settings and view their statistics, install the https://wiki.freepbx.org/pages/viewpage.action?pageId=28180526[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 ++ +---- +sudo fwconsole list +sudo fwconsole -h +sudo fwconsole restart +sudo fwconsole ma list +sudo fwconsole ma -h +sudo fwconsole ma showupgrades +sudo fwconsole ma upgradeall +---- //// @@ -203,15 +221,29 @@ It is possible that FreePBX restarts much more reliably when run on a MIN-sized === 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]. +_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_ + +. Apache's `/var/lib/php/asterisk_sessions/` directory might also be needed for NGINX? ++ +If not, the https://github.com/iiab/iiab/blob/master/roles/pbx/tasks/freepbx.yml#L147-L168[configuration of /var/lib/php/asterisk_sessions/] might be run made conditional, using `when: not pbx_try_nginx` + +. The https://github.com/iiab/iiab/blob/master/roles/pbx/tasks/freepbx.yml#L208-L211[installation of /etc/odbc.ini] for CDR (Call Detail Records) database `asteriskcdrdb` might benefit from compiling the ODBC driver for aarch64, per http://mghadam.blogspot.com/2021/03/install-asterisk-18-freepbx-15-on.html ? + +. 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] + === 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! +In February 2019, This https://github.com/iiab/iiab/tree/master/roles/pbx[pbx] Ansible playbook was originally inspired by Yannik Sembritzki's https://github.com/Yannik/ansible-role-asterisk[Asterisk] and https://github.com/Yannik/ansible-role-freepbx[FreePBX] Ansible work from 2017-2019. + +In August 2021 it was overhauled, with thanks to these 3 especially: + +* "Official" recipe: https://wiki.freepbx.org/display/FOP/Installing+FreePBX+16+on+Debian+10.9 +* Comprehensive & recent recipe for Raspberry Pi: http://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/ + +Thank you to _ALL_ who've contributed, including Lemuel D'Souza, Jerry Vonau, Adam Holt and Anish Mangal!