Contents – Basic Setup

  1. Next steps after downloading the image
  2. Determine hostname / IP address
  3. Basic configuration
  4. Call test
  5. Email setup
  6. Changing passwords
  7. 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:

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:

2. Determine hostname / IP address

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.

SSH login:

ssh root@raspbx

Web GUI:


On Macintosh, use raspbx.local instead:

ssh root@raspbx.local

Web GUI:


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:


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:


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

Choose your timezone:


Configure locale settings:

dpkg-reconfigure locales

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

dpkg-reconfigure keyboard-configuration

4. Call test

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:


Outbound CallerID can be set to <12345678> or any other number of your choice.
Configure an outbound route with these dial patterns:
toll-free outbound routes

5. 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:


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 *

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:


This configures the sender address of all outgoing mail to

Finally, to activate your configuration run:


You can test your email setup with this command:


A test email should reach your inbox shortly.

6. 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:


To change the FreePBX login select AdminAdministrators 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 SettingsAdvanced 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.

7. More documentation

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


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:


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.

2. Security: HowTo for Asterisk and Fail2Ban

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.

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


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

Then create /etc/resolv.conf with contents:


Then reload:

/etc/init.d/dnsmasq restart