iiab/roles/pbx/README.rst

==========
PBX README
==========

This 'pbx' playbook adds `Asterisk <https://asterisk.org/>`_ and `FreePBX <https://freepbx.org/>`_ to Internet-in-a-Box (IIAB) for VoIP and SIP functionality e.g. for rural telephony.

This initial release (for IIAB 6.7 in February 2019) supports Ubuntu 18.04, Debian 9 "Stretch" — and experimentally supports Raspberry Pi: `#1467 <https://github.com/iiab/iiab/issues/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. 

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

Using It
--------

Prior to installing IIAB, make sure your `/etc/iiab/local_vars.yml <http://wiki.laptop.org/go/IIAB/FAQ#What_is_local_vars.yml_and_how_do_I_customize_it.3F>`_ contains::

  pbx_install: True
  pbx_enabled: True

Optionally, you may want to enable `chan_dongle <https://github.com/wdoekes/asterisk-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 and proceed with initial configuration (no login/password is required initially — you will be asked to set this up).

You can monitor the FreePBX service with command::

  systemctl status freepbx

Raspberry Pi Known Issue
------------------------

As of 2019-02-14, "systemctl restart freepbx" fails more than 50% of the time when run on a `BIG-sized <http://wiki.laptop.org/go/IIAB/FAQ#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F>`_ 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 `contact us <http://wiki.laptop.org/go/IIAB/FAQ#What_are_the_best_places_for_community_support.3F>`_ if you can assist here in any way: `#1493 <https://github.com/iiab/iiab/issues/1493>`_

Raspberry Pi Zero W Warning
---------------------------

Node.js applications like Asterisk/FreePBX, Node-RED and Sugarizer `won't work <https://nodered.org/docs/hardware/raspberrypi#swapping-sd-cards>`_ on Raspberry Pi Zero W (ARM6) if you installed Node.js while on RPi 3 or 3 B+ (ARM7).  If necessary, run ``apt remove nodejs`` then ``cd /opt/iiab/iiab`` then `./runrole nodejs <https://github.com/iiab/iiab/blob/master/roles/nodejs/tasks/main.yml>`_ *on the Raspberry Pi Zero W itself* — before proceeding to install Asterisk/FreePBX, Node-RED and/or Sugarizer.

Attribution
-----------

This 'pbx' playbook was heavily inspired by Yannik Sembritzki's `Asterisk <https://github.com/Yannik/ansible-role-asterisk>`_ and `FreePBX <https://github.com/Yannik/ansible-role-freepbx>`_ Ansible work, Thank You!
Update README.rst 2019-02-09 18:12:45 +00:00			`==========`
Add a README to PBX role 2019-01-19 04:50:38 +00:00			`PBX README`
Update README.rst 2019-02-09 18:12:45 +00:00			`==========`
Add a README to PBX role 2019-01-19 04:50:38 +00:00
Update README.rst 2019-02-10 14:29:00 +00:00			This 'pbx' playbook adds `Asterisk <https://asterisk.org/>`_ and `FreePBX <https://freepbx.org/>`_ to Internet-in-a-Box (IIAB) for VoIP and SIP functionality e.g. for rural telephony.

Update README.rst 2019-02-11 19:13:36 +00:00			This initial release (for IIAB 6.7 in February 2019) supports Ubuntu 18.04, Debian 9 "Stretch" — and experimentally supports Raspberry Pi: `#1467 <https://github.com/iiab/iiab/issues/1467>`_
Update README.rst 2019-02-10 14:29:00 +00:00
Update README.rst 2019-02-11 20:12:10 +00:00			`What Asterisk & FreePBX Do`
			`--------------------------`
Add a README to PBX role 2019-01-19 04:50:38 +00:00
Update README.rst 2019-02-09 18:12:45 +00:00			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.
Add a README to PBX role 2019-01-19 04:50:38 +00:00
Update README.rst 2019-02-11 20:12:10 +00:00			`FreePBX is a web-based open source GUI (graphical user interface) that controls and manages Asterisk (PBX), the open source communication server.`
Add a README to PBX role 2019-01-19 04:50:38 +00:00
			`Using It`
			`--------`

			Prior to installing IIAB, make sure your `/etc/iiab/local_vars.yml <http://wiki.laptop.org/go/IIAB/FAQ#What_is_local_vars.yml_and_how_do_I_customize_it.3F>`_ contains::

			`pbx_install: True`
			`pbx_enabled: True`

Update README.rst 2019-02-09 18:12:45 +00:00			Optionally, you may want to enable `chan_dongle <https://github.com/wdoekes/asterisk-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::
PBX: Update README.rst with chan_dongle information 2019-01-19 05:20:48 +00:00
			`asterisk_chan_dongle: True`

Update freepbx default port to 83 2019-06-22 17:09:12 +00:00			`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).`
Add a README to PBX role 2019-01-19 04:50:38 +00:00
Update README.rst 2019-02-11 19:14:21 +00:00			`You can monitor the FreePBX service with command::`
Add a README to PBX role 2019-01-19 04:50:38 +00:00
			`systemctl status freepbx`

Update README.rst 2019-02-14 14:45:38 +00:00			`Raspberry Pi Known Issue`
			`------------------------`

Update README.rst 2019-02-14 14:47:24 +00:00			As of 2019-02-14, "systemctl restart freepbx" fails more than 50% of the time when run on a `BIG-sized <http://wiki.laptop.org/go/IIAB/FAQ#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F>`_ install of IIAB 6.7 on RPi 3 or RPi 3 B+.
Update README.rst 2019-02-14 14:45:38 +00:00
			It is possible that FreePBX restarts much more reliably when run on a MIN-sized install of IIAB? Please `contact us <http://wiki.laptop.org/go/IIAB/FAQ#What_are_the_best_places_for_community_support.3F>`_ if you can assist here in any way: `#1493 <https://github.com/iiab/iiab/issues/1493>`_

Update README.rst 2019-02-13 03:04:01 +00:00			`Raspberry Pi Zero W Warning`
			`---------------------------`

Update README.rst 2019-02-13 03:22:25 +00:00			Node.js applications like Asterisk/FreePBX, Node-RED and Sugarizer `won't work <https://nodered.org/docs/hardware/raspberrypi#swapping-sd-cards>`_ on Raspberry Pi Zero W (ARM6) if you installed Node.js while on RPi 3 or 3 B+ (ARM7). If necessary, run ``apt remove nodejs`` then ``cd /opt/iiab/iiab`` then `./runrole nodejs <https://github.com/iiab/iiab/blob/master/roles/nodejs/tasks/main.yml>`_ on the Raspberry Pi Zero W itself — before proceeding to install Asterisk/FreePBX, Node-RED and/or Sugarizer.
Update README.rst 2019-02-13 03:04:01 +00:00
Add a README to PBX role 2019-01-19 04:50:38 +00:00			`Attribution`
			`-----------`

Update README.rst 2019-02-10 14:29:00 +00:00			This 'pbx' playbook was heavily inspired by Yannik Sembritzki's `Asterisk <https://github.com/Yannik/ansible-role-asterisk>`_ and `FreePBX <https://github.com/Yannik/ansible-role-freepbx>`_ Ansible work, Thank You!