Contents – Basic Setup
- Next steps after downloading the image
- Determine hostname / IP address
- Basic configuration
- Call test
- Email setup
- Changing passwords
- More documentation
Contents – Advanced Topics
- Fax gateway
- Security: HowTo for Asterisk and Fail2Ban
- Running RasPBX without Internet connection
- GSM VoIP Gateway with Chan_dongle
- Security Considerations
- Backup your System
- Running RasPBX from an External USB HDD or Thumb Drive
Instructions on how to write the downloaded image to your card can be found here:
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:
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:
Once your RPi is booted, you need to know it’s 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.
On Macintosh, use raspbx.local instead:
In case this is not successful you can check your router’s 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:
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:
After this step your ssh client will warn about a changed host key on your next ssh connect.
Choose your timezone:
Configure locale settings:
Configure keyboard settings (not needed when working with ssh only):
Once basic configuration is finished, you might want to test outbound calling straight away. All newer images from 2017 and later ship with a default trunk included, provided by our sponsor Star Communication. Use this trunk to dial toll-free numbers in the U.S. for free. Log in to the FreePBX GUI, create a Chan_SIP extension and click the Apply Config button. Use your SIP capable phone and connect to this extension. You are ready to call U.S. based toll-free numbers in international format, using the +1 prefix (+1800xxxxxxx, +1844xxxxxxx, +1855xxxxxxx, +1866xxxxxxx, +1877xxxxxxx, +1888xxxxxxx). Just search Google for “U.S. toll free numbers” to get some example numbers and call them from anywhere in the world to test your setup.
In case you are running an existing installation with an older image, it is easy to add the testing trunk as well. In FreePBX, go to Connectivity, Trunks and use Add SIP (chan_sip) Trunk. Set a trunk name both in General and SIP Settings and insert this in PEER Details:
type=peer qualify=no host=switch.starcompartners.com port=5060
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:
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:
Add your credentials at the bottom of this file in the following format:
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 provider’s 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:
On the bottom of this file add:
root: firstname.lastname@example.org asterisk: email@example.com
This configures the sender address of all outgoing mail to firstname.lastname@example.org.
Finally, to activate your configuration run:
You can test your email setup with this command:
A test email should reach your inbox shortly.
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:
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.
Further documentation on how to work with the FreePBX GUI can be found here:
Fax gateway support in RasPBX is provided by HylaFAX, an optional feature which needs to be installed manually by calling:
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:
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:
The default user to connect to HylaFAX is root with empty password.
Fail2Ban can be installed easily by calling:
This installer includes all steps described by Razvan Turtureanu’s 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 don’t decide to install Fail2Ban.
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
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: