From Gentoo Wiki
Jump to:navigation Jump to:search
Article status
This article needs wikification.
This article has some todo items:

BlueBox is a web based PHP configuration and management GUI for FreeSWITCH and Asterisk switching libraries. It supports multi-tenancy, skinning, and is completely open-source.

BlueBox can be used with database and file replication to scale up to thousands of registered devices and simultaneous phone calls. It can operate in the cloud or on the premise.

It originally developed from FreePBXv3.

The following two blogs on VOIP PBX useful may be useful:


Install the following prerequisites:


Please first install FreeSWITCH following the FreeSWITCH Wiki

There are many USE options for FreeSwitch. Not all of them compile for me.

[TODO] -- Add list here of which work and which don't compile.

After installing FreeSWITCH, there is a post-installation message from portage that a backup of the default configuration files has been saved to: /usr/share/doc/freeswitch-9999/conf

But a "diff -r /etc/freeswitch /usr/share/doc/freeswitch-9999/conf" shows differences. So I made my own copy:

root #cp -a /etc/freeswitch /etc/freeswitch.orig
root #ln -s /etc/freeswitch.orig /opt/freeswitch/conf.orig

Also, portage seems to install the freeswitch configuration directory twice:

  • once into /etc/freeswitch
  • and a second time into /etc/freeswitch/freeswitch

A "diff" for each file/folder in /etc/freeswitch/* and /etc/freeswitch/freeswitch/* shows no differences. Is this a mistake?

Double check FreeSWITCH permissions: -- I think during BlueBox installation I may have done a "chown -R apache.freeswitch /opt/freeswitch".

If apache needs read access to /opt/freeswitch during BlueBox installation, the ownership/permissions need to be reset as follows or you cannot run freeswitch as user "freeswitch":

CODE Changing ownership/permissions
chown -R root:freeswitch "/etc/freeswitch"
        chmod -R u=rwX,g=rX,o=   "/etc/freeswitch"

        # prefix
        chown -R root:freeswitch "/opt/freeswitch"
        chmod -R u=rwX,g=rX,o=   "/opt/freeswitch"
        # allow read access for things like building external modules
        chmod -R u=rwx,g=rx,o=rx "/opt/freeswitch/"{lib*,bin,include}
        chmod    u=rwx,g=rx,o=rx "/opt/freeswitch"

        # directories owned by the freeswitch user
        for x in db run log cores storage recordings; do
                chown -R freeswitch:freeswitch "/opt/freeswitch/${x}"

Also, the /etc/init.d/freeswitch script tries to change the pid file from the default for FreeSwitch from /opt/freeswitch/run/ to /var/run/

FreeSwitch insists on writing its pid to /opt/freeswitch/run/, but the Gentoo init script looks for the pid in /var/run/

So my solution is to change the init script:

CODE Updated init script
start() {
        local OPTS
        [ -n "${FREESWITCH_USER}" ] && \
                OPTS="${OPTS} -u ${FREESWITCH_USER}"
        [ -n "${FREESWITCH_GROUP}" ] && \
                OPTS="${OPTS} -g ${FREESWITCH_GROUP}"
        [ -n "${FREESWITCH_OPTS}" ] && \
                OPTS="${OPTS} ${FREESWITCH_OPTS}"
        ebegin "Starting Freeswitch"
        ulimit -s 240
        start-stop-daemon --start --quiet --exec ${FREESWITCH_BIN} \
                --pidfile /opt/freeswitch/run/ -- -nc ${OPTS}
        eend $?

Web server

Install a web server such one of the following:

  • Apache — an efficient, extensible web server. It is one of the most popular web servers used the Internet.
  • nginx — a robust, small, high performance web server and reverse proxy server.


Install PHP.


Install a database backend such as:

Database setup

Setup the MySQL database:

root #mysql -u root -p
mysql>CREATE USER 'bluebox'@'localhost' IDENTIFIED BY 'bluebox';
mysql>GRANT ALL PRIVILEGES ON bluebox.* TO 'bluebox'@'localhost';
mysql>SHOW GRANTS FOR bluebox@localhost;

If you make a mistake and need to start over:

root #mysql -u root -p
mysql>REVOKE ALL PRIVILEGES, GRANT OPTION ON bluebox.* FROM 'bluebox'@'localhost';
mysql>DROP DATABASE bluebox;

Installing Bluebox

Adapted from Bluebox FreeSwitch install guide (CentOS v5.x, Freeswitch v1.0.x, Bluebox).

Install BlueBox git source into top level root of web server:

root #cd /var/www/localhost/htdocs
root #chown -R freeswitch:freeswitch /var/www/localhost/htdocs/bluebox
root #cd /var/www/localhost/htdocs/bluebox
root #./

When the install asks you for the web user name change default ("apache") to "freeswitch" (without quotes). Everything else can remain at default (just repeatedly press Enter when it asks).

Increase the memory_limit for PHP:

root #sed -i 's/memory_limit = 32M/memory_limit = 128M/g' /etc/php/apache2-php5.3/php.ini

Restart apache:

root #/etc/init.d/apache2 restart

/opt/freeswitch/conf is a symlink to /etc/freeswitch.

Ownership on the configuration files will need changed to allow apache to make changes before the BlueBox configuration GUI can run:

root #chown -R apache.freeswitch /etc/freeswitch

Browse to "http://your.web.server/bluebox/" and run the installer. I went with the defaults but changed the password and email address for the administrator. I also unchecked the option for installing sample data.

I got a warning about conflicting files:

CODE Conflicts
Conflicting Files
 Conflicting configuration files will be permanently erased if you continue!

I just continued.

After configuring BlueBox, my default configuration was as follows:

FILE /var/www/localhost/htdocs/bluebox/config/database.php
'type'     => 'mysql',
 'user'     => 'bluebox',
 'pass'     => 'bluebox',
 'host'     => '',
 'port'     => '3306',
 'socket'   => FALSE,
 'database' => 'bluebox'

You probably will want to change the password for the user "bluebox".

Next edit /var/www/localhost/htdocs/bluebox/bluebox/config/config.php and disable the installer:

FILE /var/www/localhost/htdocs/bluebox/bluebox/config/config.php
config['installer_enabled'] = FALSE;

Starting FreeSWITCH

There appears to be no man installation for FreeSWITCH. So use --help to get freeswitch command line options:

root #/opt/freeswitch/bin/freeswitch --help
These are the optional arguments you can pass to freeswitch
        -nf                    -- no forking
        -u [user]              -- specify user to switch to
        -g [group]             -- specify group to switch to
        -help                  -- this message
        -version               -- print the version and exit
        -waste                 -- allow memory waste
        -core                  -- dump cores
        -rp                    -- enable high(realtime) priority settings
        -lp                    -- enable low priority settings
        -np                    -- enable normal priority settings (system defaults)
        -vg                    -- run under valgrind
        -nosql                 -- disable internal sql scoreboard
        -heavy-timer           -- Heavy Timer, possibly more accurate but at a cost
        -nonat                 -- disable auto nat detection
        -nonatmap              -- disable auto nat port mapping
        -nocal                 -- disable clock calibration
        -nort                  -- disable clock clock_realtime
        -stop                  -- stop freeswitch
        -nc                    -- do not output to a console and background
        -ncwait                -- do not output to a console and background but wait until the system is ready before exiting (implies -nc)
        -c                     -- output to a console and stay in the foreground
        -conf [confdir]        -- specify an alternate config dir
        -log [logdir]          -- specify an alternate log dir
        -run [rundir]          -- specify an alternate run dir
        -db [dbdir]            -- specify an alternate db dir
        -mod [moddir]          -- specify an alternate mod dir
        -htdocs [htdocsdir]    -- specify an alternate htdocs dir
        -scripts [scriptsdir]  -- specify an alternate scripts dir

I got an error when starting FreeSWITCH:

root #/opt/freeswitch/bin/freeswitch -c -rp -u freeswitch
Error: stacksize -1 is too large: run ulimit -s 240 from your shell before starting the application.
auto-adjusting stack size for optimal performance...
Cannot open pid file /opt/freeswitch/run/

So I just added ulimit -s 240 to the start routine of /etc/init.d/freeswitch.

Some useful fs_cli (FreeSWITCH command line interface) for debugging, tracing:

 sofia status
 sofia status profile sipinterface_1
 sofia status profile sipinterface_1 reg
 sofia loglevel all 9
 sofia global siptrace on
 console loglevel debug
 expand sofia contact <sip user account>

Configuring FreeSWITCH with BlueBox

Browse to "http://your.web.server/bluebox/".

Install additional modules:

System->Package Manager A few modules have prerequisite modules so if you get an error, install the prerequisite. A few pairs of modules conflict, e.g.:

  • "Freeswitch" and "Asterisk"
  • "Endpoint Manager" and "Provisioner"
  • "Media File" and "Media Manager"

I chose "Freeswitch", "Endpoint Manager" and "Media File" and installed every remaining module except those for a call center.

Bluebox came pre-installed with three sip interfaces "Connectivity" -> "SIP Interface"

Authenticated SIP	 Auto Detect	5060	Required    Edit|Delete
Authenticated SIP - NAT Auto Detect	5070	Required    Edit|Delete
Unauthenticated SIP	 Auto Detect	5080	None	    Edit|Delete

Use the FreeSWITCH CLI to see your interfaces:

freeswitch@myhost> sofia status 
                    Name          Type                                       Data      State
          sipinterface_2       profile            sip:mod_sofia@      RUNNING (0)
             voicemail_1         alias                             sipinterface_2      ALIASED
          sipinterface_1       profile            sip:mod_sofia@      RUNNING (0)
          sipinterface_3       profile            sip:mod_sofia@      RUNNING (0)
           alias                             sipinterface_1      ALIASED
3 profiles 2 aliases

Now configure users, devices, voicemail boxes, endpoints and assign numbers. It facilitates configuring your sip device if you first configure

  • the Users ("Organization" -> "User Manager")
  • their Voicemail Boxes ("Applications" -> "Voicemail Boxes")
  • the Endpoints ("Applications" -> "Endpoints")

and then

  • the sip phones ("Applications" -> "Devices")

The passwords for the users must be alphanumeric but the passwords for the sip devices and voicemail boxes need not be so. To keep things simple I used the same identifying string for device names, sip accounts, extensions. For example, Device Name "101" associated with user "John Doe" used sip account "101" and was assigned extension "101" and unanswered calls were transferred to the voicemail box for 101 (extension 201) All used the same password except for the the required alphanumeric password for the User Account for John Doe.

If you decide to have a default Multitenant system, then your sip registrations will use "user@domain" instead of just "user" for the User Account. Make sure that your user:password (or user@domain:password) for each Device in bluebox matches what you have configured for each sip phone.

First try to get sip registration working before attempting secure sip (sips) registration or encrypted media (srtp). FreeSWITCH also has support for end-to-end encryption using zrtp (see FreeSWITCH Wiki: ZRTP). But you must use a sip phone which supports zrtp such as the softphone Zfone. Unfortunately, my Snom phones don't support zrtp and Snom has no plans to do so.

Note that bluebox adds your sip devices to /etc/freeswitch/directory/default.xml. So check and verify that your users have been added there.

Verify that your sip phones have registered with FreeSWITCH:

sofia status profile sipinterface_1
Name                    sipinterface_1
Domain Name             N/A
Auto-NAT                false
Pres Hosts       
Dialplan                XML
Context                 multitenant_routing_context
Challenge Realm         auto_to
URL                     sip:mod_sofia@
BIND-URL                sip:mod_sofia@
HOLD-MUSIC              N/A
CODECS IN               G7221@32000h,G7221@16000h,G722,PCMU,PCMA,GSM
CODECS OUT              G7221@32000h,G7221@16000h,G722,PCMU,PCMA,GSM
TEL-EVENT               101
DTMF-MODE               rfc2833
CNG                     13
SESSION-TO              0
MAX-DIALOG              0
NOMEDIA                 false
LATE-NEG                false
PROXY-MEDIA             false
AGGRESSIVENAT           false
STUN-ENABLED            true
CALLS-IN                2
CALLS-OUT               1

Show registrations for sipinterface:

sofia status profile sipinterface_1 reg
<... excerpt ..>
Call-ID:        3c26701f3482-2ou8k0j6yqug
User:           101@
Contact:        "John Doe" <sip:101@>
Agent:          snom360/8.4.32
Status:         Registered(UDP)(unknown) EXP(2012-05-18 20:26:09) EXPSECS(2869)
Host:           pbx
Port:           2048
Auth-User:      101
MWI-Account:    101@voicemail_1

Now that our phones have registered with FreeSWITCH, check that you have a dial tone and can dial an internal extension.


If you want to test SIP from outside your network, apply for a free DID from IPKall (Washington State).

Just select an area code and choose a "SIP phone number" which can be any alphanumeric string, eg. "IPKall". Enter the "SIP Proxy" for your FreeSWITCH server, eg. "". Make sure you specify a SIP port of 5080 instead of the default 5060.

BlueBox uses different SIP ports to listen on for each different SIP interface, e.g.:

  • Authenticated SIP Auto Detect 5060
  • Authenticated SIP - NAT Auto Detect 5070
  • Unauthenticated SIP Auto Detect 5080

Then go to "Routing -> Number Manager" and add your new number:

  • Manage -> Number: "IPKall"
  • Manage -> Type: Internal
  • Device (Pick a destination such as Device "101")
  • Contexts -> Inbound Routes
  • Number Pools -> Device

Now add a trunk for IPKall "Connectivity -> Trunk Manager":

  • Trunk Name: "IPKall"
  • Trunk Type: "SIP Interface"
  • Server: ""
  • Bind To Interface: "Unauthenticated SIP"
  • Made from these Contexts: "Inbound Routes"
  • Caller ID Name: "ipkall"
  • Caller ID Number: <DID number emailed to you by IPKall>

Now try phoning the IPKall DID phone number emailed to you. I got a busy signal, so I had to edit "Connectivity -> SIP Interfaces -> Unauthenticated SIP" and change "Inbound Calls -> Default Incoming Context" from "AUTO(Multitenant)" to "Inbound Routes" since I opted not to have a multitenant system.

NAT traversal for SIP

See NAT Traversal RTP SIP

Configuring a dialplan (TODO)

Now we need to configure various components for a dialplan. BlueBox's modules make configuring a dialplan rather straight forward. A few things from FreePBX seem to be missing:

  • A simple way to call an extension to record an IVR prompt for use with an AutoAttendant
    • BB does however allow you to upload a pre-recorded media file

or to use text-to-speach (flite, cepstral) for your prompts

  • No iax or dahdi (freetdm) modules -- only sip
    • Early versions of FreePBX did not have a dahdi configuration utility for managing chan_dahdi_additional.conf, however you could still manually edit the chan_dahdi_custom.conf.

It should be possible to do something similar with FS+BB. The configuration files created by BB begin with "bluebox_", can one though edit other configuration files and have them included in the BB dialplan? without getting clobbered by BB?

Auto attendant

  • AutoAttendant

Time based routes

  • Time Based Routes

Ring groups

  • Ring Groups


  • Conferences

Feature codes

  • Feature Codes such as CheckingVoicemail, etc.


  • Trunks: DAHDI (PSTN), SIP, IAX

Saving the BlueBox configuration

The BlueBox configuration files are stored in /opt/freeswitch/conf -> /etc/freeswitch.

Make a copy:

root #cp -a /etc/freeswitch /etc/bluebox

Now make a symlink:

root #ln -sf /etc/bluebox /opt/freeswitch/conf.bluebox

If you also installed FusionPBX, then do similarly:

root #ln -sf /etc/fusionpbx /opt/freeswitch/conf.fusionpbx

Before starting freeswitch or using the GUI just remember to copy either /etc/{bluebox,fusionpbx} to /etc/freeswitch or change the symlink:

root #ln -sf /etc/bluebox /opt/freeswitch/conf
 Authenticated SIP - NAT Auto Detect	5070	Required    Edit|Delete
> /dev/null