Documentation

Contents – Basic Setup

  1. How to flash the downloaded image
  2. Determine hostname / IP address
  3. Basic configuration
  4. Email setup
  5. Initial Asterisk setup
  6. Changing passwords
  7. More documentation

Contents – Advanced Topics

  1. Fax gateway
  2. Security: HowTo for Asterisk and Fail2Ban
  3. GSM VoIP Gateway with Chan_dongle
  4. Security Considerations
  5. Backup your System
  6. Running RasPBX from an External USB HDD or Thumb Drive
  7. Uninterruptible Power Supply (UPS) for BeagleBone Black – a DIY Project

Basic Setup

1. How to flash the downloaded image

A micro-SD card with 2GB or more is required for the image. On Windows, use 7-Zip to extract the .img.xz file and write it to your SD card with Win32 Disk Imager. Read the section Update board with latest software on the original Getting Started for more details:
http://beagleboard.org/Getting%20Started

On Linux, the card can be directly flashed with:

xz -dc raspbx-bbb-*.img.xz > /dev/sdX

Replace /dev/sdX with the actual device of your SD card.

Insert the SD card into your (powered-down) board, hold down the user/boot button and apply power, either by the USB cable or 5V adapter. On subsequent boots, the BBB automatically detects the SD card and boots from it, pressing the boot button is only required once. Eject the SD card (while powered off) to boot the original Angström image from the internal eMMC.

If you don’t want to mess with your eMMC contents, you can just keep running RasPBX from the SD card and you’re fine. But it is also possible to write the same image to the internal eMMC.

Writing the image to the internal eMMC storage

The board has to be booted from an SD card in order to flash the eMMC. Don’t boot from the eMMC and try to flash it at the same time!
Follow the steps above to create an SD card and boot from it. Copy the compressed .img.xz file to a USB thumb drive as well. Insert this thumb drive into the BBB USB host port and mount it:

mount /dev/sda1 /mnt

You can determine available disk space with df:

root@raspbx:~# df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       7.9G  1.7G  6.2G  22% /mnt

You might want to save the original eMMC contents to your thumb drive just to be save. Make sure to have at least 2GB free space available (4GB is required for the latest BBB revisions).

dd bs=1M if=/dev/mmcblk1 of=/mnt/emmc_orig_contents.img

Once copying is done the output should look like this:

1832+0 records in
1832+0 records out
1920991232 bytes (1.9 GB) copied, 404.815 s, 4.7 MB/s

If you ever want to revert your eMMC to it’s original state:

dd bs=1M if=/mnt/emmc_orig_contents.img of=/dev/mmcblk1

Copy the RasPBX image to your eMMC:

xz -dc /mnt/raspbx-bbb-*.img.xz > /dev/mmcblk1

When you’re done, unmount the thumb drive:

umount /mnt/

Power down the board, remove SD card and power it again. Your board boots RasPBX from the internal eMMC.

Expand root partition

There is an easy way to expand the root partition to utilize the complete space of your SD card. Log in to the console, install and run raspi-config (ignore the errors of dpkg, apt-get will fix them):

cd /tmp
wget http://repo.raspbx.org/download/raspi-config_20121028_all.deb
dpkg -i raspi-config_20121028_all.deb
apt-get -f install
raspi-config

This tool has originally been written for the Raspberry Pi, most of the menu options won’t work. But expand root partition does work on the BBB as well.

2. Determine hostname / IP address

Once your BBB 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 BBB.

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 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 beaglebone, and run the command:

ifconfig

Of course you can also use the gadget USB network or serial to log into your device.

3. Basic configuration

After your BBB has booted successfully, log in either on the console or by ssh with user root and password beaglebone. 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 keyboard settings (not needed when working with ssh only):

dpkg-reconfigure keyboard-configuration

4. Email setup

Email delivery from your BBB 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 BBB. 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 provider’s SMTP host IP address here. For Google Mail, this is currently gmail-smtp-msa.l.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. Initial Asterisk setup

Point your browser to the BBB’s hostname or IP address (http://raspbx).

The default login to FreePBX is:
user: admin
password: admin

For inital setup please follow this guide:
http://www.freepbx.org/support/documentation/installation/first-steps-after-installation

Most of the configuration steps presented here apply to the BBB as well. If you are going to use SIP technology, you absolutely need to follow section 5, “Configure Asterisk SIP Settings”.

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:

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.

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

Further details concerning optional features can be found on the original Asterisk for Raspberry Pi website:

  1. Fax gateway
  2. Security: HowTo for Asterisk and Fail2Ban
  3. GSM VoIP Gateway with Chan_dongle
  4. Security Considerations
  5. Backup your System

24 thoughts on “Documentation”

  1. Robert Schwartz

    Hi – nice write-up. Only have one problem:

    I tried to Copy the RasPBX image to the eMMC as described on this page, but every-time it just bricks my BBB. I can’t even boot backup with the working RasPBX on the mSD card. None of the user LEDs light up, even if I hold down the User button. The only way to bring my board back to life is to reflash the BBB with the instructions found here:

    http://circuitco.com/support/index.php?title=Updating_The_Software#Flashing_the_eMMC

    The exact cmd line I used was:

    xz -dc /mnt/raspbx-bbb-28-05-2013.img.xz > /dev/mmcblk1

    Am I doing something wrong? Is the image I’m using not the same as what was tested by the author?

    Thanks!

    -Rob

  2. Gernot Post author

    The instructions above have been tested multiple times, and worked fine so far. But it is possible the thumb drive you are using contains errors, and therefore the image file is damaged. You can verify the image file by comparing the checksums with the ones provided above:

    sha1sum raspbx-bbb-28-05-2013.img.xz

    or

    md5sum raspbx-bbb-28-05-2013.img.xz

    Like this you can be sure to have the exact same file as the one used by the author.

  3. Gregg DeMasters

    Thanks for the info. I am seeking just a bit more info. Whenever I update my system, I seem to run out of drive space, leaving the database unusable. Any recommended procedures to alleviate this problem, such as expanding the partition on the SD card (running from SD) or moving partitions from the eMMC to the SD card (running from eMMC)?

    1. Gernot Post author

      On the eMMC there is just not more space than 2GB. I recommend to run from the SD card only in your case. You can resize the root partition on your card either by inserting it into a Linux machine and using GParted, which is pretty straight forward, or by doing it manually on the device itself:
      http://www.gigamegablog.com/2012/09/26/beaglebone-101-linux-tricks-for-backing-up-and-resizing-your-microsd-card/
      Scroll down to Resizing a 4G Image on an 8G Card, it describes the whole process. It’s a bit more complicated to do but should work as well.

  4. rcfa

    I need to compile a WiFi device driver, and I think I need the linux header files for the distribution. Where can we get these?

    1. Gernot Post author

      The exact kernel shipped with the image is 3.8.13-bone18 and can be found here:
      http://rcn-ee.net/deb/raring-armhf/v3.8.13-bone18/

      To install the headers, run:
      wget http://rcn-ee.net/deb/raring-armhf/v3.8.13-bone18/linux-headers-3.8.13-bone18_1.0raring_armhf.deb
      dpkg -i linux-headers-3.8.13-bone18_1.0raring_armhf.deb

      I’m not sure if this is already sufficient to build your module. The base distro used for the image is Ubuntu Raring Armhf with kernel 3.8.13-bone18.

  6. rcfa

    Just to clarify: the pre-built drivers I tried to install, but they won’t load due to
    “ERROR: could not insert ‘mtnet7601Usta’: Exec format error”
    so it seems I have to build the drivers from source.

    1. Gernot Post author

      The modules have to match the kernel version, otherwise they won’t load. That’s probably the reason for this failure.

      1. rcfa

        Understood, it was just an attempt, because compiling won’t work without the kernel header files, and those aren’t available.

  7. rcfa

    One more clarification: the rt2800usb.ko module is supposed to work with the device, in theory. In practice, it doesn’t load. Even doing an
    sudo apt-get install linux-firmware-nonfree
    didn’t fix that; which is why I was trying to get things going with the specific driver in question.
    So if someone has an idea how to get the rt2800usb driver to work, that would of course be fine, too.

    1. rcfa

      Turns out that although the device should be covered by the rt2800usb driver, the device ID string isn’t compiled in:

      root@waldi:/lib/modules# modinfo rt2800usb | grep v148Fp
      alias: usb:v148FpF101d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp5372d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp5370d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp3572d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp8070d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp3370d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp3072d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp3071d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp3070d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp2870d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp2770d*dc*dsc*dp*ic*isc*ip*in*
      alias: usb:v148Fp2070d*dc*dsc*dp*ic*isc*ip*in*

      but:
      root@waldi:~# lsusb
      Bus 001 Device 002: ID 148f:7601 Ralink Technology, Corp.
      Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
      Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

      So I carefully binary-edited the rt2800usb.ko file with emacs’ hexl-mode, both the byte-flipped hex value somewhere in the binary, and in the alias text string in the binary, but the system won’t load a so modified binary, either; bummer.

      1. rcfa

        Here the diffs to the files:
        root@waldi:/lib/modules/3.8.13-bone18/kernel/drivers/net/wireless/rt2x00# diff <(xxd rt2800usb.ko) <(xxd rt2800usb.ko.orig)
        391c391
        0001860: 4670 4631 3031 642a 6463 2a64 7363 2a64 FpF101d*dc*dsc*d
        1861c1861
        0007440: 0300 8f14 01f1 0000 0000 0000 0000 0000 …………….

        but unfortunately, I get an error message when doing any of these:

        modprobe -f rt2800usb
        ERROR: could not insert ‘rt2800usb’: Exec format error
        insmod /lib/modules/$(uname -r)/kernel/drivers/net/wireless/rt2x00/rt2800usb.ko
        Error: could not insert module /lib/modules/3.8.13-bone18/kernel/drivers/net/wireless/rt2x00/rt2800usb.ko: Unknown symbol in module

        So linux is a bit too smart for its own good, or I’m too stupid for linux 😉

  8. Frank

    Hi Gernot, great, everything works just great here on a bbb, I didnt have any problem installing or configuring anything. Some 3g/4g usb modems works too on the bbb, witch is great cus the raspberry sucks ass on the usb power part.

    However I have been running my head to the wall 300 times trying to change the hostname. a simple matter I did 1000’s times before on warious linux systems, but what is going on with raspbx? Did you figgure how to change it?

    Cheers,
    /Frank

    1. Gernot Post author

      Thanks for the compliments! Changing the hostname is easy. Just edit /etc/hostname

      nano /etc/hostname

      then reboot. Voila! 🙂

  9. Chris

    Hi Gernot,

    I’m very interested because I was trying to use chan_dongle on raspbx, playing sound through alsa. That audio quality was pretty bad — crackling and distortion despite many attempts to set jitter in both chan_dongle and alsa — so when I found your port I switched over. Unfortunately, the console audio is worse on the bbb; it sounds like I’m talking through a fan. I can’t tell if this is a jitter issue, frame rate, buffer, or what. aplay works great, and tests like
    rec -t alsa -r 16010 -c 1 -e signed-integer > play
    also work perfectly.

    For about 20% of the time, the audio will tighten up and be perfect. Playing music on hold starts choppy but soon becomes clear; a voice over the gsm line will occasionally snap to clear then quickly snap back.

    To be clear, the gsm modem that I’m using (e303) does support voice, and it’s working, just a very large vibrato that would go perfectly with “crimson and clover” but not much else. Any thoughts?

    C.

    1. Gernot Post author

      Is this only happening when routing the audio through Alsa? Or do you experience the same audio problems when calling a SIP phone on your network?

  10. Shane

    Just set up the image on a new BBB and am quite impressed. A few tips in case anyone wants to tweak a bit:
    the internal EMC memory is approx 3x faster in my testing than an microSD card. So I put the BBB image on the internal EMC and installed a MicroSD for additional space. You need to edit uEnv.txt to boot from /dev/mmcblk1 as the EMC becomes mmcblk1 when an SD card is installed. The fstab also needs adjusting in this regard. I copied /var over to the microSD and adjusted so that /var is a separate FS from the EMC, freeing up lots of EMC space if needed. This probably breaks raspbx-backup but that needs some work also as it tried to cp mysql rather than using mysqldump but I digress.
    Quite a few packages can be removed to free up EMC space and services stopped to free memory. In particular, udhcpd is a dhcp server which isn’t needed, dnsmasq is only needed if you have a potentially unreliable DNS configuration and all of the locales and man-db can go if your only language is English. I also removed samba as it is not necessary to mount windows shares and installed cifs-utils for CIFS mounting.
    Anything console related can go. console-setup, kbd etc provided your only access will be via ssh. Hopefully I didn’t break anything critical but the PBX happily runs on.

    1. Dan

      The comment about the EMC speed is interesting. I thought the internal memory was “class 4” (not sure where I read that but my MicroSD card is “Class 10”, and 16GB. I was just going to run off the SD card but if the EMC is really faster I may switch.

    2. Dan

      So I put the BBB image on the internal EMC and installed a MicroSD for additional space. You need to edit uEnv.txt to boot from /dev/mmcblk1 as the EMC becomes mmcblk1 when an SD card is installed. The fstab also needs adjusting in this regard. I copied /var over to the microSD and adjusted so that /var is a separate FS from the EMC, freeing up lots of EMC space if needed.

      Can you explain this a bit further? I may go this route also. Thanks in advance!

      Cheers,
      Dan

  11. andy

    Hi everybody,
    I wish to set up a sip server for a small office; I’m not a professional, only a hobbyst. I can’t understand a thing: will I need a static ip or I can arrange with a dynamic one?
    Thanks!

    1. Gernot Post author

      You can also work with a dynamic IP of course. It is usually best practice to assign a fixed IP with DHCP from your router.

Comments are closed.