Scalelite and Dial-In numbers

Dialing into a BigBlueButton conference using freeswitch

The built-in WebRTC-based audio in BigBlueButton is very high quality audio. Still, there may be cases where users need to be able to dial into the conference bridge using a telephone number.

BigBlueButton has allowed to add a phone number to the conference bridge since long-long time ago. And when dealing with one single BigBlueButton server, that configuration is really simple (as explained in the official documentation) because the FreeSWITCH service that is part of BigBlueButton is the one that recives and handles the forwarded incoming calls.

Dial-In Architecture for a standalone BigBlueButton deployment.

But when dealing with an scaled deployment through a Load Balancer and a pool of BigBlueButton servers, that functionality comes with a new challenge. This is because based on that basic configuration, the Internet Telephone Service Provider would need to know the specific server to which the the dial in call would be forwarded to.

The solution is to add an extra FreeSWITCH call server in the middle to act as a Call Processing Server (a.k.a. Call Server) and make the LoadBalancer generate a) a dialplan to prompt the caller for the conference number and b) a dialplan to route the user to the BigBlueButton server where the meeting is running.

Dial-In Architecture for a scaled BigBlueButton deployment.

That is now possible with the release of Scalelite version 1.4, and here are the steps for its configuration.

Prerequisits

To follow this tutorial it is needed:

• A phone number from a Internet Telephone Service Provider such as Twilio or Flowroute. (For this deployment we used Twilio).
• A stock FreeSWITCH server wich will be acting as the Call Server, that can be in or out the Scalelite an BigBlueButton networks, and ideally deployed in its own machine. (For this deployment we used a Debian 10 server with FreeSWITCH version: 1.10.8 on a DigitalOcean Droplet).
• A fully functional deployment of Scalelite (v1.4 or later) with at least one BigBlueButton Server enabled in its pool. (We used a kubernetes cluster on AWS EKS for Scalelite and a pool of two BigBlueButton Servers running on AWS EC2 instances, but the outcome should be the same using the Scalelite Systemd or Docker Compose deployments, and BigBlueButton hosted anywhere else).

Scalelite Configuration

The configuration of Scalelite is really simple. It is just a matter of setting the proper values to the environment variables (which in fact can work out of the box with default values) and make them match with the FreeSWITCH Call Server configuration.

• VOICE_BRIDGE_LEN: The length (number of digits) of voice bridge numbers generated by Scalelite. The Default value is 7. Shorter voice bridge numbers are easier to enter, but also easier to guess through random tries. The BigBlueButton configuration must support the selected length. And by default BigBlueButton supports anything between 5 to 10 digits.
• USE_EXTERNAL_VOICE_BRIDGE: Whether or not to try to use the voiceBridge number passed by the BigBlueButton API client. Defaults to false. If the API client generates numbers compatible with the BigBlueButton configuration, this can be changd to true to use them instead. It is important to note that Scalelite will ignore the voice bridge number provided, and generate a new one, when the number is already in use by a different meeting.
• FSAPI_PASSWORD: The Password (for "Basic" authentication) to access the freeswitch dialplan API. By default Scalelite used the first LOADBALANCER_SECRET as the password. It can also be set this to an empty string to disable authentication.
• FSAPI_MAX_DURATION: Maximum duration for voice calls handled by the freeswitch dialplan integration in minutes. The defaults value is set to MAX_MEETING_DURATION if that is set, otherwise no limit. Probably the best choice is to set a limit here to ensure the expenses are not exceded due to people not hanging up calls.

Settings

In our kubernetes deployment we only added this variable to the configmap.yaml manifest:

MAX_MEETING_DURATION: "360"

On a Systemd deployment this variable should be added to /etc/default/scalelite, and on a Docker Compose (Lazy) deployment to the .env file as:

MAX_MEETING_DURATION=360

Restart the scalelite-api pod or docker container and Scalelite is ready to go.

FreeSWITCH Call Server Configuration

Let us remember that this is a stock FreeSWITCH server.

Configuration file

The configuration file is /etc/freeswitch/autoload_configs/xml_curl.conf.xml and it should look like this:

<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
  <binding name="dialplan sl-example-com">
    <param name="gateway-url" value="https://sl.example.com/fsapi" bindings="dialplan"/>
    <param name="gateway-credentials" value="fsapi:mysecret"/>
    <param name="auth-scheme" value="basic"/>
  </binding>
</bindings>
</configuration>

• The dialplan name can be anything.
• The gateway-url must match the URL of the scalelite server and it must include the endpoint for the fapi.
• The gateway-credentials can be either the Scalelite first secret defined as LOADBALANCER_SECRET or the one defined as FSAPI_PASSWORD.
• The auth-scheme should always be basic.

Restart the FreeSWITCH service and the FreeSWITCH Call Server is ready to go.

BigBlueButton Configuration

The important set up in BigBlueButton is to allow SIP calls in. Therefore there are three things to consider here:

Network firewall

First, it is not uncommon to have a Network firewall (such as a security group in AWS). In such cases the SIP port (5060) and the ones used for UDP audio (16384 to 32768) must be opened so the FreeSWITCH Call Server can forward the calls directly to the network where the BigBlueButton Server is deployed.

Built-in firewall

As recommended in the documentation, BigBlueButton stock comes with UFW as a built-in firewall. The the same ports need to be opened so the forwarded calls can be received by the BigBlueButton Server.

sudo ufw allow from FREESWITCH_CALL_SERVER_IP_ADDRESS to any port 5060
sudo ufw allow 16384:32768/udp

Configuration file

Lastly, the configuration file is /opt/freeswitch/conf/dialplan/public/bbb_gw.xml and it should look like this:

<include>
  <extension name="bbb_voice_gw" continue="true">
    <condition>
      <action application="set" data="bbb_authorized=true"/>
      <action application="transfer" data="${destination_number} XML default"/>
    </condition>
  </extension>
</include>

Restart the FreeSWITCH service and the BigBlueButton Server is ready to go.