Documentation

Contents Basic Setup

1. Next steps after downloading the image
2. Determine hostname / IP address
3. Basic configuration
4. Email setup
5. Changing passwords
6. More documentation

Contents Advanced Topics

1. Fax gateway
2. Security: HowTo for Asterisk and Fail2Ban
3. Running RasPBX without Internet connection
4. GSM VoIP Gateway with Chan_dongle
5. Security Considerations
6. Backup your System
7. Running RasPBX from an External USB HDD or Thumb Drive

Basic Setup
1. Next steps after downloading the image
Instructions on how to write the downloaded image to your card can be found here:
http://elinux.org/RPi_Easy_SD_Card_Setup

The image is only utilizing 4GB of your card, even if you bought a bigger one. On a
bigger card, you can make more space available to your root partition by running on the
console of your booted RPi:

raspi-config

Select the option expand_rootfs. (Resizing with raspi-config did not work with the 2015
images but is fine again since 2016.)
If you rather prefer to do this manually, one of the easiest ways is using GParted on
Linux. Details can be found here:
http://elinux.org/RPi_Resize_Flash_Partitions#Manually_resizing_the_SD_card_using_
a_GUI_on_Linux

2. Determine hostname / IP address

Once your RPi is booted, you need to know its hostname or IP address for ssh login or
to open the web GUI. On Windows computers, you can just use the hostname raspbx to
access your RPi.
SSH login:

ssh root@raspbx

Web GUI:

http://raspbx

On Macintosh, use raspbx.local instead:

ssh root@raspbx.local

Web GUI:

http://raspbx.local

In case this is not successful you can check your routers DHCP client list, and search
for the IP associated with the name raspbx.
If this is still not working out, you can always just connect an HDMI monitor and USB
keyboard, log in to the console with user root, password raspberry, and run the
command:

ifconfig

3. Basic configuration
After your RPi has booted successfully, log in either on the console or by ssh with user
root and password raspberry. Follow these steps to complete the initial configuration:

Create new ssh host keys to have individual keys for every setup:

regen-hostkeys

After this step your ssh client will warn about a changed host key on your next ssh
connect.

Choose your timezone:

configure-timezone

Configure locale settings:

dpkg-reconfigure locales

Configure keyboard settings (not needed when working with ssh only):

dpkg-reconfigure keyboard-configuration

4. Email setup
Email delivery from your RPi is needed if you plan to have voicemails sent to users by
email. Email already works in the default configuration using Exim4 as MTA. By
default, Exim is configured to directly send mails to the recipient MX hosts. This is
however discouraged, as many email providers classify emails coming from dynamic IP
addresses as spam. To avoid this, you need to set a smarthost. Unless you have an open
SMTP server on your network that can be used as smarthost without authentication, you
will need to specify SMTP authentication credentials as well. It is basically possible to
use almost any publicly available freemailer as smarthost with the RPi. Have username
and password as well as SMTP hostname (sometimes also referred to as outgoing mail
server) of the email account you are going to use ready. Run on the console:

dpkg-reconfigure exim4-config

On the first configuration page select mail sent by smarthost; received via SMTP or
fetchmail. On the following pages just keep the default values by pressing enter, until
you reach the page starting with Please enter the IP address or the host name of a mail
server. Here, enter the SMTP hostname of your email provider. Again, keep default
values on the remaining pages.
Then, edit the file passwd.client by running:

nano /etc/exim4/passwd.client

Add your credentials at the bottom of this file in the following format:

SMTP_HOSTNAME:USERNAME:PASSWORD

In most cases, the SMTP hostname used in this file is identical to the hostname used as
smarthost before. If email fails to work, specify the reverse lookup of your email
providers SMTP host IP address here. For Google Mail, set this to *.google.com

Some email providers also require you to use sender addresses identical to one of the
public email adresses of your account. In this case, edit:

nano /etc/email-addresses

On the bottom of this file add:

root: your_email@someisp.com
asterisk: your_email@someisp.com

This configures the sender address of all outgoing mail to your_email@someisp.com.

Finally, to activate your configuration run:

update-exim4.conf

You can test your email setup with this command:

send_test_email your_email@someisp.com

A test email should reach your inbox shortly.

5. Changing passwords
Once you are done with basic installation, you might want to change the following
important passwords to keep your setup safe. As long as your system is running with a
private IP address behind a router with all ports closed, these passwords will only affect
people trying to log in from inside your network, as no one can log in from outside
anyway.

Change the password for SSH or console login with:

passwd

To change the FreePBX login select Admin Administrators in FreePBX. On the right
side of the page below Add User select admin. The password can be changed here.

There are 2 more passwords that should be changed. In FreePBX open Settings
Advanced Settings. Find the field Asterisk Manager Password and change this
password. On the same page, search for User Portal Admin Password and change the
password for the ARI administrator login as well.

6. More documentation
Further documentation on how to work with the FreePBX GUI can be found here:

http://www.freepbx.org/support/documentation

http://wiki.freepbx.org/

Advanced Topics
1. Fax gateway
Fax gateway support in RasPBX is provided by HylaFAX, an optional feature which
needs to be installed manually by calling:

install-fax

This command is added with upgrade #5, see the downloads page for details. Make sure
you have been running raspbx-upgrade and your system is up to date, otherwise this
command is not available.

After installation is complete, you can configure a fax extension at your choice. This
can also be skipped and done later by calling:

add-fax-extension
This is configuring HylaFAX, Iaxmodem and FreePBX. An additional extension is
added to FreePBX which can be used as inbound destination for your fax DID. Faxes to
this extension will be emailed to the address specified during the add-fax-extension run.

It is possible to have as many fax extensions as required by calling add-fax-extension

multiple times. Each extension can me mapped to a different email address, thus having
several virtual fax machines with different recipients.

For sending faxes, any HylaFAX client such as Winprint HylaFAX or any other can be
used. A complete list can be found here:
http://www.hylafax.org/content/Desktop_Client_Software

The default user to connect to HylaFAX is root with empty password.

2. Security: HowTo for Asterisk and Fail2Ban

Fail2Ban can be installed easily by calling:

install-fail2ban

This installer includes all steps described by Razvan Turtureanus how-to for installing
Fail2Ban with Asterisk on RasPBX. Read the complete tutorial in the forum. The last
section other security tips gives a good overview on security in general, be sure to read
this even if you dont decide to install Fail2Ban.

3. Running RasPBX without Internet connection

If Internet connection is not continuously present or not present at all, 2 issues can
appear that prevent calling between extensions:

A. On system boot, current time is obtained through NTP. Asterisk only starts after time
has been set correctly, to avoid problems that have been seen in connection with a large
time jump on the system. If Asterisk is started with wrong time first and time is properly
set later, audio on calls can be seriously distorted. Thus, the boot scripts only start
Asterisk after time has been set, and in setups without Internet connection Asterisk will
not start by default. To overcome this, install fake-hwclock:

apt-get install fake-hwclock

It saves the time on shutdown and loads it again on reboot.

Update: Dnsmasq is installed and configured as described below with upgrade #10. The
steps below are not needed if all the latest upgrades are installed.

B. Asterisk gets into trouble when DNS lookups fail, leaving an unstable system. This
can be fixed by installing dnsmasq:

apt-get install dnsmasq

configure:
cd /etc
mv resolv.conf resolv.conf.dnsmasq

edit /etc/dnsmasq.conf, change this section

# Change this line if you want dns to get its upstream servers from
# somewhere other that /etc/resolv.conf
resolv-file=/etc/resolv.conf.dnsmasq

Then create /etc/resolv.conf with contents:

nameserver 127.0.0.1

Then reload:

/etc/init.d/dnsmasq restart

____________________________________________________________________________

FAQ
This is a compilation of questions asked in the forums as well as a few other things of
general interest.

Contents

1. What is the performance of Asterisk running on the Raspberry Pi?

2. How to configure a static IP address?
3. How do I interface the RPi with an analog line from my telecoms provider?
4. How do I interface the RPi with an ISDN line from my telecoms provider?
5. Uploading of music on hold doesnt work, how can I fix it?
6. Can I install System Admin or any other module that requires Zend Guard
Loader?
7. How can I run Asterisk without FreePBX?
8. How can I get WiFi connectivity on RasPBX?
9. How can I compile Asterisk myself?
10. How to call anonymously with chan_dongle?
11. How to send voicemail in mp3 format?
12. How to install Chan_SCCP?
13. Where is the SILK codec enabled in FreePBX?
14. Can I use the local audio device for console calling?
15. How to build a VoiceXML IVR?
16. How to upgrade to Asterisk 13?
17. Where can I find sample config files?
18. How to enable FreePBX dashboard updates?
What is the performance of Asterisk running on the
Raspberry Pi?
In a typical setup with RasPBX, 10 concurrent calls are possible on a Pi 1. This is also
the case for conferences, meaning 10 participants can join a conference. More than 10
calls do work, but audio quality decreases considerably with every additional call. See
also:
http://sourceforge.net/p/raspbx/discussion/general/thread/4975db40/#eb2a

How to configure a static IP address?

On all images from 2016 and later edit /etc/dhcpcd.conf:

nano /etc/dhcpcd.conf

Insert at the bottom of this file:

interface eth0
static ip_address=192.168.0.10/24
static routers=192.168.0.1
static domain_name_servers=192.168.0.1

Replace the values above with your addresses.

On older images until 2015 edit the file /etc/network/interfaces:

nano /etc/network/interfaces

In this file, remove the line

iface eth0 inet dhcp

and insert instead:

iface eth0 inet static

address 192.168.0.50
netmask 255.255.255.0
gateway 192.168.0.1
dns-nameservers 192.168.0.1

Replace the values above with your addresses. Then run:

service networking restart

How do I interface the RPi with an analog line from

my telecoms provider?
Up to date there is no hardware available that is interfacing with an analog line and can
be directly connected to the RPi. Calls have to go over Ethernet using any of the VoIP
protocols supported by Asterisk. Devices with a PSTN FXO port translating the analog
line to SIP are for example the Linksys SPA3102 or the Obihai OBi110. These can be
configured as SIP trunks in Asterisk.

How do I interface the RPi with an ISDN line from my

telecoms provider?
Same answer as above concerning analog lines. A device capable of converting ISDN to
SIP is the AVM FRITZ!Box 7170. Newer models such as the 7390 should work as well.

Uploading of music on hold doesnt work, how can I fix

it?
The default Asterisk MOH files are provided in several different formats to avoid
transcoding whenever possible. FreePBX only recognizes .wav files and does not delete
the other transcodes when deleting a file within the FreePBX GUI. Before uploading
new files remove the old MOH files first (or move them to a different location):

cd /var/lib/asterisk/moh
rm *.alaw *.g729 *.gsm *.ulaw *.wav

Can I install System Admin or any other module that

requires Zend Guard Loader?
Unfortunately no. Zend Guard Loader is closed source and only available on x86
platforms.

How can I run Asterisk without FreePBX?

If the FreePBX GUI is not needed and should be prevented from overwriting the
Asterisk config files, it can be disabled (without deinstalling it):

update-rc.d freepbx remove

Apache can also be disabled if the GUI is not needed at all:

update-rc.d apache2 remove

This file needs to be downloaded and placed in /etc/init.d/:

http://repo.raspbx.org/download/asterisk

chmod 755 /etc/init.d/asterisk

update-rc.d asterisk defaults

This is a startup script from contrib/init.d from the Asterisk sources. On reboot, Asterisk
starts directly, without using the amportal startup script from FreePBX. After making
these changes, a complete reboot is required.
How can I get WiFi connectivity on RasPBX?
A power supply rated 1A or better 1.2A or more is required to power both the RPi and
your WiFi adapter. Alternatively a powered USB hub can also be used.
Before buying a WiFi adapter, make sure its on the verified peripherals list:

http://elinux.org/RPi_VerifiedPeripherals#Working_USB_Wi-Fi_Adapters

The following description has been tested with an Edimax EW-7811Un adapter, but
should also work in the same way with most of the supported adapters.

Install required packages:

apt-get install wireless-tools wpasupplicant

Edit the file /etc/network/interfaces and add at the bottom of this file:

auto wlan0
allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-ssid your-ssid-here-no-quotes
wpa-psk "your-passphrase-here-with-quotes"

Then restart your RPi:

reboot

Your WiFi connection should show up as wlan0, wlan1, etc. configured with an IP of
your network when calling:

ifconfig

A more detailed description can be found here.

How can I compile Asterisk myself?

Before using your own self-compiled Asterisk on RasPBX, remove the installed
asterisk13 or asterisk11 package first:

apt-get remove asterisk11 asterisk13

If you dont remove it, your changes will be overwritten on the next asterisk13 or
asterisk11 package update.

Follow these steps to get the menuselect screen for Asterisk 13:

apt-get install build-essential libsqlite3-dev libxml2-dev

libncurses5-dev libncursesw5-dev libmysqlclient-dev libiksemel-dev
libssl-dev libnewt-dev libusb-dev libeditline-dev libedit-dev curl
libcurl4-gnutls-dev libjansson-dev
cd /usr/src/
wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-13-
current.tar.gz
tar -xvzf asterisk-13-current.tar.gz
cd asterisk-*
./configure
make menuconfig

Once you have reached the menu, select from Add-ons: res config mysql, app mysql,
cdr mysql. When you are done, select Save & Exit.
Then continue:

make
make install

Just in case you ever want to revert using the compiled binary package from the
RasPBX repository again, you can install it any time with:

apt-get install asterisk13

This will overwrite your own compiled version with the package from the repository.

How to call anonymously with chan_dongle?

If you would like to suppress your caller id when calling out through chan_dongle
(GSM/3G), edit the file /etc/dongle.conf and change the original setting
callingpres=allowed_passed_screen to

callingpres=prohib

How to send voicemail in mp3 format?

By default, voicemail recordings are presented in wav format, encoded with a gsm
codec when sent as attachments to emails. These can be sent in mp3 format instead with
the following modifications (make sure upgrade #15 is installed):

In FreePBX, go to Settings Voicemail Admin. Change the setting format from

wav49|gsm|wav to:

wav

As mailcmd enter

/usr/bin/mp3_voicemail

How to install Chan_SCCP?

Chan_SCCP-b is a replacement Channel Driver for chan_skinny in the Asterisk
Channel Driver Library. Detailed information including full documentation can be
found on the original Chan_SCCP Website:

http://chan-sccp-b.sourceforge.net/
Chan_SCCP can be installed directly from the repository:

apt-get update
apt-get install chan-sccp-ast13

In case you are still running Asterisk 11, replace the package name chan-sccp-ast13
with chan-sccp, which is the correct package for Asterisk 11. After installation, sample
configuration files can be found in

/var/lib/chan-sccp/conf

A valid sccp.conf configuration file has to be created in /etc/asterisk. Please read the
original documentation on how to set up and configure Chan_SCCP. Make sure to
disable chan_skinny after installing Chan_SCCP, or Asterisk will fail to start.

Where is the SILK codec enabled in FreePBX?

in FreePBX open Settings Asterisk SIP Settings, scroll down to Other SIP Settings,
and enter

allow = silk8

Possible bandwidths include 8, 12, 16 and 24, add appropriate allow statements for each
bandwidth you want to use.

Can I use the local audio device for console calling?

On the RPi the built-in headphone jack can be used as an audio device to make calls
with chan_alsa. First copy the config file:

cp /usr/share/asterisk/configs/alsa.conf /etc/asterisk/

Then follow this tutorial: Overhead Pager over Soundcard

When using a USB sound card for two-way audio, set the desired audio device
accordingly in /etc/asterisk/alsa.conf

How to build a VoiceXML IVR?

An advanced application for Asterisk is available from i6net. Read more details here:
https://wiki.voximal.com/doku.php?id=installation_guide:raspbx
http://www.voximal.com/home_en/

How to upgrade to Asterisk 13?

On images with Asterisk 11, Asterisk 13 is provided as an optional install. A Debian
Jessie based image (Feb. 2015 or later, older images are not suported) is required.
Follow these installation steps:
raspbx-upgrade
apt-get update
amportal stop
apt-get purge asterisk11
apt-get install asterisk13
amportal start

Once installed your Asterisk 13 will be continuously updated with patches and security
fixes as usual.

Where can I find sample config files?

Starting with Asterisk 11.18.0 sample config files can be found in:

/usr/share/asterisk/configs/

They can be useful for Asterisk modules that are not configured by FreePBX. Copy the
files you need to /etc/asterisk and edit as necessary, but watch out to not overwrite
existing files generated by FreePBX.

How to enable FreePBX dashboard updates?

The FreePBX dashboard scheduler is disabled on RasPBX by default, because it writes
lots of data to the Mysql database every minute depending on the configuration. This
has previously reduced the lifetime of SD-cards in many cases. On RasPBX the
dashboard scheduler is only run once every hour. To enable dashboard updates every
minute edit this file:

nano /etc/raspbx/raspbx.conf

and set this option

ENABLE_DASHBOARD_SCHEDULER=1

This config file will be processed on the next hourly cron run, which is usually at
minute 17 of every hour.

_____________________________________________________________________________