Welcome to the installation guide for BigBlueButton 1.1.

    BigBlueButton is an open source web conferencing system for online learning. The goal of the project is to enable teachers to engage remote students in a high-quality online learning experience.

    BigBlueButton 1.1, our latest release, offers faster desktop sharing, closed captioning, and breakout rooms (see overview of BigBlueButton 1.1 for details).

    This document is for system administrators and developers wanting to setup and install BigBlueButton 1.1. Specifically, it covers installation of BigBlueButton on a Ubuntu 16.04 64-bit server, configuring BigBlueButton to use a hostname and SSL certificate, and, if BigBlueButton is running behind a firewall, configuring the firewall to pass through connections on specific ports to the BigBlueButton server.

    For developers, when installing BigBlueButton a virtual machine (VM) or a Linux Container (LXD) running on a local network, you can typically skip configuring a hostname, SSL certificate, and firewall. Use FireFox to test as this browser does not require a SSL certificate for use with WebRTC.

    For administrators, if you want to setup BigBlueButton on a public server for use by others, you will need to configure BigBlueButton with a valid hostname and SSL certificate (not a self-generated certificate). Furthermore, if you are installing BigBlueButton behind a firewall, you will also need to configure the firewall to pass through specific connections to the BigBlueButton server (the details are given in this document).

    We recommend installing BigBlueButton 1.1 on a new Ubuntu 16.04 64-bit server; specifically, one that does not already have web applications installed (such as plesk). Such applications create subtle conflicts with the installation and running of BigBlueButton that are difficult to resolve.

    If you want to upgrade a BigBlueButton 1.0 (or earlier) server, we recommend to starting with a separate clean Ubuntu 16.04 64-bit server, install BigBlueButton 1.1 on it, and then transfer over existing recordings.

    If you encounter difficulties with the installation, see http://bigbluebutton.org/support for how to engage the BigBlueButton community reach out to companies that offer commercial support and hosting for BigBlueButton.

    Before you install

    Before you type sudo apt-get install BigBlueButton, go through this section to make sure your server meets the minimum requirements.

    Minimum server requirements

    The minimum server requirements for installing BigBlueButton 1.1 are

    • Ubuntu 16.04 64-bit OS
    • 4 GB of memory with swap enabled (8 GB of memory is better)
    • Quad-core 2.6 GHZ CPU (or faster)
    • TCP ports 80, 443,and 1935 are accessible
    • TCP port 7443 is accessible if you intend to configure SSL (recommended), otherwise port 5066 is accessible
    • UDP ports 16384 - 32768 are accessible
    • Port 80 is not in use by another application

    Other recommendations are

    • 500G of free disk space (or more) for recordings
    • 100 Mbits/sec bandwidth (symmetrical)
    • Dedicated (bare metal) hardware (not virtualized)

    Why do we recommend a bare metal server? BigBlueButton uses FreeSWITCH for processing of incoming audio packets and FreeSWITCH works best in a non-virtualized environment (see FreeSWITCH recommended configurations). You can still run BigBlueButton on a virtual server (such as shown in the install video), but you’ll get best performance on dedicated hardware.

    If you are a developer setting up a BigBlueButton server for dev and testing, you don’t need 500G free for such recordings (40G would be more than sufficient).

    If you want to install BigBlueButton on Amazon EC2, launch a 64-bit Xenial instance from Canonical’s list of list of supported AMI. We recommend running BigBlueButton on a c4.xlarge (or greater CPU) instance.

    What about bandwidth for users? For end-user accessing the BigBlueButton server we recommend (a minimum of) 1.0 Mbits/sec download speed and 0.5 Mbits/sec upload speed. If the presenter intends to share his or her desktop, then we recommend (a minimum of) 1.0 Mbits/sec upload speed.

    Check server specs

    Got a Ubuntu 16.04 64-bit server setup? Great, let’s run through some quicks configuration checks to make sure the server is ready for an error-free install. Doing these quick steps will save time later on.

    First, check that the locale of the server is en_US.UTF-8. To check the locale, enter the following command and check its output matches LANG="en_US.UTF-8.

    $ cat /etc/default/locale
    LANG="en_US.UTF-8"
    

    If you don’t see LANG="en_US.UTF-8", then enter the following commands to set the local to en_US.UTF-8.

    $ sudo apt-get install language-pack-en
    $ sudo update-locale LANG=en_US.UTF-8
    

    Next, logout and then log back into your SSH session – this will reload the locale configuration for your session – and run the above command cat /etc/default/locale again. Verify you see only the single line LANG="en_US.UTF-8".

    Note: If you see an additional line LC_ALL=en_US.UTF-8, then remove the entry for LC_ALL from /etc/default/locale and logout and then log back in once more.

    Next, check that your server has (at lest) 4G of memory using the command free -h. Here’s the output from one of our test servers.

    $ free -h
                  total        used        free      shared  buff/cache   available
    Mem:            31G        5.9G        314M        1.8G         25G         21G
    Swap:           31G        360M         31G
    

    If you see a value for Mem: in the total column less than 4G (the above example is showing 31G), then your server has insufficient memory to run BigBlueButton. You need to increase the server’s memory to (at least) 4G.

    Next, check that the server has Ubuntu is 16.04.

    $  cat /etc/lsb-release
    DISTRIB_ID=Ubuntu
    DISTRIB_RELEASE=16.04
    DISTRIB_CODENAME=xenial
    DISTRIB_DESCRIPTION="Ubuntu 16.04.x LTS"
    

    Next, check that your server is running the 64-bit version of Ubuntu 16.04.

    $ uname -m
    x86_64
    

    Next, check that your server supports IPV6.

    $ ip addr | grep inet6
    inet6 ::1/128 scope host 
    ...
    

    If you do not see the line inet6 ::1/128 scope host then after you install BigBlueButton you will need to modify the configuration for FreeSWITCH to disable support for IPV6.

    A word on the choice of Linux distribution. We (the core developers) have designed, developed, installed, and tested BigBlueButton 1.1 on Ubuntu: 16.04 64-bit (Xenial Xerus). That’s what we recommend you use. We have not tested BigBlueButton 1.1 on any other version of Ubuntu (or Linux).

    Why the focus on Ubuntu 16.04? It’s a choice of quality over quantity. Long ago we concluded that its better for the project to have solid, well-tested, well-documented installation for a specific version of Linux that works really, really well than to try and support may variants of Linux and have none of them work well.

    Have a Hostname and SSL certificate

    (If you are a developer setting up BigBlueButton on a local VM for yourself only, then you can likely skip this section.)

    We recommend assigning your BigBlueButton server a fully qualified domain name (FQDN), such as bigbluebutton.example.com, and configuring that server with secure sockets layer (SSL) certificate. Doing this will enable nginx, the web server that gets installed with BigBlueButton, to serve content via secure hypertext transfer protocol (HTTPS). Without HTTPS enabled some browsers (such as Chrome) will not let the use share their web cam or microphone. Also, without HTTPS enabled, some browsers will complain about insecure content.

    In short, on any server used in production, setup of a domain name and valid SSL certificate is a must.

    For obtaining a domain name, there are many good domain name registrars such as GoDadday and Network Solutions.

    For obtaining a SSL certificate, after you install BigBlueButton, there is more detailed information in the section Obtain an SSL certificate.

    Configure the firewall (if required)

    (Again, if you are a developer setting up BigBlueButton on a local VM for testing, you can likely skip this section).

    The simplest network configuration for a BigBlueButton server is the server has a single external IP address, the server is on the public Internet (and thus directly accessible by your users), and there is no firewall (virtual or physical) between users an the server. Here is an example of such a setup with the BigBlueButton server having a (fictional) IP address 203.0.113.1 with hostname bigbluebutton.example.com.

    Install

    In this simple network configuration, BigBlueButton should work out-of-the-box after installation. This is because the packaging scripts automatically configure BigBlueButton using the first non-loopback IP address.

    A variation of this setup occurs when the server has multiple network interfaces, but the external IP is still the first network interface (such as eth0) picked up by the installation scripts.

    Install

    Again, in this case, the packaging scripts will correctly configure BigBlueButton to use the external IP address and you can skip the remainder of this section and proceed to Installing BigBlueButton.

    Don’t worry if your server’s IP address changes, BigBlueButton comes with a configuration utility called bbb-conf that lets you change all of BigBlueButton’s configuration files to use any IP address or hostname.

    If there is a firewall between your users and the BigBlueButton server, then you will need to first configure the firewall to forward specific connections from external clients to the internal BigBlueButton server; otherwise, users will not be able to access BigBlueButton.

    The following diagram gives a typical setup with an external firewall (your setup will, of course, have different IP address and hostnames).

    Install

    In this example, all users must connect to the BigBlueButton server via the uniform resource locator (URL) https://bigbluebutton.example.com/. This hostname resolves to the IP address 203.0.113.1 which is the firewall. The firewall must forward specific connections (described below) to the BigBlueButton server running at IP address 10.0.2.12.

    Configuring your firewall

    When BigBlueButton is protected behind a firewall, you need to configure the firewall to forward the following incoming connections to BigBlueButton:

    • TCP ports 80, 443, 1935, and 7443
    • UDP ports in the range 16384 - 32768

    In the case where you have installed BigBlueButton on Amazon EC2, you need to add rules to the server’s associated security group (which serves as a firewall) to allow the above TCP and UDP connections.

    After you have made the changes, before proceeding to the installation, take a moment and test that you have configured the firewall to correctly forward the above connections.

    Testing the firewall

    To test connections on various ports needed by BigBlueButton, you will use a tool called netcat to listen for connections on specific ports on the BigBlueButton server. You’ll use the same tool on a server external to the firewall to generate connections. If the connection goes throw, then the firewall is forwarding the packets.

    To test, first install netcat on the BigBlueButton using the following command:

    $ sudo apt-get install netcat
    

    Next, stop BigBlueButton with the command sudo bbb-conf --stop. We can now run netcat to listen on ports and try connecting from an external computer. As root, run the following command:

    # netcat -l 7443
    

    netcat is now going to echo to the terminal any text it receives on port 7443 (you can quit the command later using Ctrl-c).

    Next, on a second computer that is external to the firewall – that is, it must go through the firewall to access the BigBlueButton server – install netcat as well. Replacing EXTERNAL_HOST_NAME with the hostname of your firewall, run the following command

    # netcat EXTERNAL_HOST_NAME 7443
    

    and type type the word ‘test’ and press ENTER.

    If the firewall is forwarding incoming connections on port 7443 to the internal BigBlueButton server, you should see the word ‘test’ appear after the netcat -l 7443 command, as in

    # netcat -l 7443
    test
    

    If the word test does not appear, double-check the firewall configuration to ensure its forwarding connections on port 7443 and then test again. You want to see the word test appear before proceeding to the installation BigBlueButton.

    Repeat these tests with ports 80, 443, and 1935.

    That covers the TCP/IP ports. Next, we need to test that UDP connections in the range 16384-32768 are forwarded as well. On your BigBlueButton server, run the following netcat command to listen for incoming data via UDP on port 17000 (here, we’re picking a port in the range 16384-32768).

    # netcat -u -l 17000
    

    Next, on a computer outside the firewall, replace EXTERNAL_HOST_NAME with the hostname of your firewall and run the command

    # netcat -u EXTERNAL_HOST_NAME 17000
    

    Type ‘test2’ into the terminal and press ENTER. You should see the word ‘test2’ appear on the terminal of the BigBlueButton server, as in

    # netcat -u -l 17000
    test2
    

    As before, it the above test fails, double-check the settings of the firewall to ensure its properly fording UDP packets in the range 16384-32768 and test again.

    When BigBlueButton is running on a server, various component of BigBlueButton need to make connections to itself using the external hostname. Programs running within the BigBlueButton server that try to connect to the external hostname should reach BigBlueButton itself.

    To enable the BigBlueButton server to connect to itself using the external hostname, edit file /etc/hosts and add the line

    EXTERNAL_IP_ADDRESS EXTERNAL_HOST_NAME
    

    where EXTERNAL_IP_ADDRESS with the external IP of your firewall and EXTERNAL_HOST_NAME with the external hostname of your firewall. For example, using the configuration in the above diagram, the addition to /etc/hosts would be

    172.34.56.78 bigbluebutton.example.com
    

    Try the above test again to ensure they work work before proceeding.

    Installation video

    To help you get started quickly, we put together an installation video that covers:

    • installing BigBlueButton 1.1 on an newly setup 16.04 64-bit server,
    • assigning a hostname, and
    • configuring the server with SSL certificate from Let’s Encrypt

    To view the video click the image below.

    BigBlueButton 1.1- Installation Video

    Note: If your BigBlueButton server will be running behind firewall, there are additional steps for configuring the firewall and BigBlueButton to enable and access for external users.

    Installing BigBlueButton 1.1

    Before you begin the installation, here’s a quick checklist to make sure you are ready:

    1. You have a Ubuntu 16.04 64-bit server that meets the minimum specifications.
    2. If the server is behind a firewall, you have configured the firewall to forward the appropriate ports to the BigBlueButton server (and tested that connections are getting through).
    3. You have a fully qualified domain name (such as bigbluebutton.example.com) that resolves to your BigBlueButton server’s IP address (or the IP address of your firewall).
    4. You have a valid SSL certificate for the hostname.

    If you are a developer setting up BigBlueButton for development or testing on a local VM, you can skip (2), (3), and (4). In this scenario, use FireFox for testing as FireFox supports WebRTC without a requiring an SSL connection.

    OK, let’s get started with the installation!

    1. Update your server

    First, make sure your server is up-to-date with latest packages and security updates.

    Login to your server via SSH. You need to have an account that can execute commands as root (via sudo). Once logged in, first ensure that you have xenail multiverse in your /etc/apt/sources.list by doing the following

    $ grep "multiverse" /etc/apt/sources.list
    

    After entering the above command you should see an uncommented line for the multiverse repository, which may look like either this

    deb http://archive.ubuntu.com/ubuntu xenial multiverse
    

    or this

    deb http://archive.ubuntu.com/ubuntu xenial main restricted universe multiverse
    

    Don’t worry if your hostname in the URL is different from the above, what’s important is you see an uncommented link that contains multiverse. If you don’t, run the following command to add the multiverse repository to your /etc/apt/sources.list file.

    $ echo "deb http://archive.ubuntu.com/ubuntu/ xenial multiverse" | sudo tee -a /etc/apt/sources.list
    

    If you are a developer installing BigBlueButton on a VM for testing and development, some of BigBlueButton’s components, such as Tomcat, need a source of entropy when starting up. In a VM the available entropy can run low and cause Tomcat to block for a long periods of time (sometimes minutes) before finishing startup. To give the VM lots of entropy, install a packaged called haveged (a simple entropy daemon):

    $ sudo apt-get install haveged
    

    If you are curious on the details behind entropy, see this link.

    Next, upgrade your server to the latest packages (and security fixes).

    $ sudo apt-get update
    $ sudo apt-get dist-upgrade
    

    If you haven’t updated in a while, apt-get may recommend you reboot your server after dist-upgrade finishes. Do the reboot now before proceeding to the next step.

    2. Install apt-get key for BigBlueButton repository

    All packages for BigBlueButton are digitally signed with the projects public key. Before installing BigBlueButton, you need to add the project’s public key to your server so apt-get can validate the signed packages. To do this, enter the following command:

    $ wget http://ubuntu.bigbluebutton.org/repo/bigbluebutton.asc -O- | sudo apt-key add -
    

    Next, so your server needs to know where to download the BigBlueButton packages. To configure the package repository, enter the following command:

    $ echo "deb http://ubuntu.bigbluebutton.org/xenial-110/ bigbluebutton-xenial main" | sudo tee /etc/apt/sources.list.d/bigbluebutton.list
    

    Finally, run apt-get to pull down the links to the latest BigBlueButton packages.

    $ sudo apt-get update
    

    3. Install BigBlueButton

    We’re now ready to install BigBlueButton.

    $ sudo apt-get install bigbluebutton
    

    That’s it. One command. This single command will install all of BigBlueButton’s core components along with all it’s necessary dependencies.

    Install

    When prompted to proceed, type ‘Y’ and press ENTER.

    Note: During install, you may see an error “Failure to download extra data files” for the ttf-mscorefonts-installer package. This is a known issue with Ubuntu 16.04. You can ignore this error.

    If the installation exits with an error before finishing, go through the checks in Before you install to see if there is a configuration error with the server. If you find an resolve any configuration errors, you can attempt to finish the installation using the command sudo apt-get install -f.

    After the installation finishes, restart all the BigBlueButton services in proper sequence using the following command:

    $ sudo bbb-conf --restart
    

    Next, run the BigBlueButton configuration utility bbb-conf --check. This utility checks BigBlueButton’s configuration and log files and looks for any potential errors that may cause problems when running.

    You should see output similar to the following (of course with a different IP address than 10.0.3.192).

    $ bbb-conf --check
    
    BigBlueButton Server 1.1.0-YY (NNN)
                        Kernel version: 4.4.0-47-generic
                          Distribution: Ubuntu 16.04.N LTS (64-bit)
                                Memory: NNNN MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): 10.0.3.192
                                  red5: 10.0.3.192
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                        websocket port: 5066
                        WebRTC enabled: true
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: 10.0.3.192
                                  port: 80
                        bbb-client dir: /var/www/bigbluebutton
    
    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties (bbb-web)
                          bbb-web host: 10.0.3.192
    
    /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp (API demos)
                                   url: 10.0.3.192
    
    /var/www/bigbluebutton/check/conf/config.xml (client check)
                          client check: 10.0.3.192
    
    /usr/share/red5/webapps/bigbluebutton/WEB-INF/red5-web.xml (red5)
                      voice conference: FreeSWITCH
    
    /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml (record and playback)
                         playback host: 10.0.3.192
    
    
    ** Potential problems described below **
    

    Any output that followed Potential problems may indicate configuration errors or installation errors. In many cases, the messages will give you recommendations on how to resolve the issue.

    At this point, your BigBlueButton server is listening to an IP address. If your a developer setting up a VM for testing/development and just want to use the IP address without a hostname, skip to the section API demos.

    Assign a hostname

    For any production BigBlueButton server, you need to assign it a hostname. If you have not done so already, use the web interface provided by your domain name service (DNS) provider and add an A record pointing to your server’s IP address (see the documentation for your DNS provider on how to do this step).

    After the A record is setup, enter the following command and EXTERNAL_HOST_NAME with the hostname of your BigBlueButton server.

    $ ping EXTERNAL_HOST_NAME
    

    Here’s an example of the output using demo.bigbluebutton.org:

    $ ping demo.bigbluebutton.org
    PING demo.bigbluebutton.org (146.20.105.32) 56(84) bytes of data.
    64 bytes from 146.20.105.32: icmp_seq=1 ttl=44 time=27.5 ms
    

    Note: If your server doesn’t allow ICMP traffic, then no bytes will be returned, but you should see your server’s IP address returned in the brackets () after the hostname.

    If the hostname is resolving to the server’s IP address (or the IP address of the firewall), next use the BigBlueButton configuration utility bbb-conf to update BigBlueButton’s configuration files to use this hostname.

    $ sudo bbb-conf --setip HOSTNAME
    

    For example, if your hostname was bigbluebutton.example.com, the command would be

    $ sudo bbb-conf --setip bigbluebutton.example.com
    

    At this point, you have BigBlueButton server listening to an IP address (or hostname) and responding to API requests. However, if you tried to login from the server’s default page with a browser, you would get an error HTTP Status 404 - /demo/demo1.jsp.

    Why? This page requires the API demos installed. We’ll cover installing the API demos in the next step.

    However, you may not need the demos if you are intending to use another front-end for the BigBlueButton server. For example, if you have a Moodle server and you want to configure the BigBlueButton Moodle Plugin to access the BigBlueButton server, you don’t need to install the API demos.

    To configure the Moodle (and other) integrations with BigBlueButton, use bbb-conf --secret tool to get your BigBlueButton server’s URL and shared secret.

    $ bbb-conf --secret
    
           URL: http://bigbluebutton.example.com/bigbluebutton/
        Secret: a7007506f1efffa497922fc34e3184dc
    

    4. Install API demos (optional)

    If you want to login to your BigBlueButton server through the landing page, install the API demos using the command

    $ sudo apt-get install bbb-demo
    

    Once installed, you’ll be able to enter your name on the home page and click ‘Join’. This will join you into the default meeting called “Demo Meeting”. You can also check out the other examples by clicking the API examples link on the home page. These are the same API demos installed at http://demo.bigbluebutton.org.

    If you are setting up a production server with custom front-end, you may want to temporarily install the API demos for testing only.

    Later on, to remove the API demos, enter the command:

    $ sudo apt-get purge bbb-demo
    

    To learn more about integrating BigBlueButton with your application, check out the BigBlueButton API documentation.

    5. Install client self-check (optional)

    BigBlueButton provides an end-user self-check application that can help you diagnose networking and configuration issues that may be preventing an end-user from accessing the server.

    To install the end-user self-check application, enter the command

    $ sudo apt-get install bbb-check
    

    The self-check application is available at your BigBlueButton server’s IP address (or hostname) with /check appended. For example, you can try out the self-check application on the BigBlueButton demo server at http://demo.bigbluebutton.org/check.

    Later on, if you wish to remove the end-user self-check page, enter the command

    $ sudo apt-get purge bbb-check
    

    6. Restart your server

    You can restart and check your BigBlueButton server at any time using the commands

    $ sudo bbb-conf --restart
    $ sudo bbb-conf --check
    

    The bbb-conf --check scans some of the log files for error messages. If you’ve done a number of configuration changes on your server, you can clear out all the log files and check the server using the --clean option, as in

    $ sudo bbb-conf --clean
    $ sudo bbb-conf --check
    

    Here is a sample output from running sudo bbb-conf --check on demo.bigbluebutton.org. This server has a SSL certificate as well.

    $ bbb-conf --check
    
    BigBlueButton Server 1.1.0-YY (NNN)
                        Kernel version: 4.4.0-28-generic
                          Distribution: Ubuntu 16.04.1 LTS (64-bit)
                                Memory: 7982 MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): demo.bigbluebutton.org
                                  red5: demo.bigbluebutton.org
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                        websocket port: 7443
                        WebRTC enabled: true
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: demo.bigbluebutton.org
                                  port: 80, [::]:80
                                  port: 443 ssl
                        bbb-client dir: /var/www/bigbluebutton
    
    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties (bbb-web)
                          bbb-web host: demo.bigbluebutton.org
    
    /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp (API demos)
                                   url: demo.bigbluebutton.org
    
    /usr/share/red5/webapps/bigbluebutton/WEB-INF/red5-web.xml (red5)
                      voice conference: FreeSWITCH
    
    /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml (record and playback)
                         playback host: demo.bigbluebutton.org
    
    
    
    ** Potential problems described below **
    # Warning: The API demos are installed and accessible from:
    #
    #    https://demo.bigbluebutton.org/demo/demo1.jsp
    #
    # These API demos allow anyone to access your server without authentication
    # to create/manage meetings and recordings. They are for testing purposes only.
    # If you are running a production system, remove them by running:
    #
    #    sudo apt-get purge bbb-demo
    

    Notice that sudo bbb-conf --check warns you the API demos installed, which enable anyone with access the server to launch a session.

    If you see other warning messages check out the troubleshooting installation.

    With BigBlueButton installed and a hostname applied, the next steps are:

    Configuring SSL on your BigBlueButton server

    You’ll want to add SSL support to your BigBlueButton server to make it more secure. Also, as of Chrome 47, Chrome users will be unable to share their microphone via WebRTC unless BigBlueButton is loaded via HTTPS.

    Configure BigBlueButton to use a domain name

    Please run all commands in this section as root.

    In order to obtain a valid SSL certificate for your server, you must have already assigned a hostname to your BigBlueButton server.

    For the purposes of documentation, we will be using the domain name “example.com”, with a BigBlueButton server hosted at “bigbluebutton.example.com”.

    Once you have a domain name and have configured it with a DNS host, add an A record pointing to your server. You can then use the bbb-conf setip command to configure BigBlueButton to use that domain name, for example:

    # bbb-conf --setip bigbluebutton.example.com
    

    Obtain an SSL certificate

    Before you can configure nginx on BigBlueButton to server content via HTTPS, you need to have a valid SSL certificate. A domain validated (sometimes called “class 1”) certificate with a 2048 bit RSA key and SHA-256 checksum is the current recommended minimum, and it should be sufficient.

    There are a number of providers that you could obtain a certificate from. Many domain name sales companies also offer certificates.

    Some well known large providers of SSL certificates include Comodo, Symantec, GoDaddy, GlobalSign, and DigiCert. In addition, free SSL certificates are available from StartSSL and CACert, with some caveats: StartSSL certificates can’t be revoked without paying a service fee, and most people do not have the root for CACert installed in their web browser.

    Each provider will give you a series of steps for generating the certificate, but they will normally include generating a private key and certificate request locally, sending the certificate request to be signed, and then receiving back the signed certificate after they have performed any required verification steps.

    To install the certificate in BigBlueButton, you will need to have files for the certificate, private key, and any intermediate certificates in PEM format.

    If you don’t yet have a SSL certificate and your server is on the Internet, you can use Let’s Encrypt to obtain a free renewable SSL certificate (expires after 90 days, but are automatically renewable). If you want to use Let’s Encrypt, then skip to setup using Let’s Encrypt.

    Configure nginx to use HTTPS

    Depending on your certificate authority (CA), you should now have 2 or more files, as follows:

    • Certificate
    • Private key
    • Intermediate certificate (there may be more than one, or could be none)

    The next step is to install the files on the server.

    Create the directory /etc/nginx/ssl:

    # mkdir /etc/nginx/ssl
    

    And now create the private key file for nginx to use (replace the hostname in the filename with your own). In addition, fix the permissions so that only root can read the private key:

    # cat >/etc/nginx/ssl/bigbluebutton.example.com.key <<'END'
    Paste the contents of your key file here
    END
    chmod 0600 /etc/nginx/ssl/bigbluebutton.example.com.key

    And the certificate file. Note that nginx needs your server certificate and the list of intermediate certificates together in one file (replace the hostname in the filename with your own):

    # cat >/etc/nginx/ssl/bigbluebutton.example.com.crt <<'END'
    Paste (in order) the contents of the following files:
      1. The signed certificate from the CA
      2. In order, each intermediate certificate provided by the CA (but do not include the root).
    END

    In addition, we’ll generate a set of 2048-bit diffie-hellman parameters to improve security for some types of ciphers. This step can take several minutes to complete, particularly if run on a virtual machine.

    # openssl dhparam -out /etc/nginx/ssl/dhp-2048.pem 2048
    

    Now we can edit the nginx configuration to use SSL. Edit the file /etc/nginx/sites-available/bigbluebutton to add the marked lines. Ensure that you’re using the correct filenames to match the certificate and key files you created above.

    server {
      server_name bigbluebutton.example.com;
      listen 80;
      listen [::]:80;
      listen 443 ssl;
      listen [::]:443 ssl;
      ssl_certificate /etc/nginx/ssl/bigbluebutton.example.com.crt;
      ssl_certificate_key /etc/nginx/ssl/bigbluebutton.example.com.key;
      ssl_session_cache shared:SSL:10m;
      ssl_session_timeout 10m;
      ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
      ssl_ciphers "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS:!AES256";
      ssl_prefer_server_ciphers on;
      ssl_dhparam /etc/nginx/ssl/dhp-2048.pem;
      

    For reference, note that the SSL settings used above are based on those proposed in https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/ and provide support for all modern browsers (including IE8, but not IE6, on Windows XP). Please note that recommended SSL settings are subject to change as new vulnerabilities are found.

    Configure FreeSWITCH for using SSL

    Edit the file /opt/freeswitch/conf/sip_profiles/external.xml and look for a line containing “ws-binding”. Change the line so it matches the following (note the change of ws-binding to wss-binding and port 5066 to 7443).

        <param name="tls-version" value="$${sip_tls_version}"/>
        <param name="wss-binding" value=":7443"/>

    If you have a firewall on your server and have opened port 5066, change the rule to now open port 7443 instead.

    Next, the websocket forwarding address in nginx. Edit the file /etc/bigbluebutton/nginx/sip.nginx and change the protocol and port on the proxy_pass line as shown:

    location /ws {
      proxy_pass https://203.0.113.1:7443;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
      proxy_read_timeout 6h;
      proxy_send_timeout 6h;
      client_body_timeout 6h;
      send_timeout 6h;
    }

    Configure BigBlueButton to load session via HTTPS

    With nginx now configured to use SSL, the next step is to configure FreeSWITCH to use HTTPS for initiating an audio connection.

    Edit /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and update the property bigbluebutton.web.serverURL to use HTTPS:

    #----------------------------------------------------
    # This URL is where the BBB client is accessible. When a user successfully
    # enters a name and password, she is redirected here to load the client.
    bigbluebutton.web.serverURL=https://bigbluebutton.example.com

    Next, edit the file /usr/share/red5/webapps/screenshare/WEB-INF/screenshare.properties and update the property jnlpUrl and jnlpFile to HTTPS:

    streamBaseUrl=rtmp://freddixon.ca/screenshare
    jnlpUrl=https://bigbluebutton.example.com/screenshare
    jnlpFile=https://bigbluebutton.example.com/screenshare/screenshare.jnlp

    You must also update the file /var/www/bigbluebutton/client/conf/config.xml to tell the BigBlueButton client to load components via HTTPS. You can do the update with a single command

    # sed -e 's|http://|https://|g' -i /var/www/bigbluebutton/client/conf/config.xml
    

    If you would ever need to revert this change, you can run the reverse command:

    # sed -e 's|https://|http://|g' -i /var/www/bigbluebutton/client/conf/config.xml
    

    Next, modify the creation of recordings so they are served via HTTPS. Edit /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml and change the value for playback_protocol as follows:

    playback_protocol: https
    

    If you have installed the API demos in step 4, edit /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp and change the value of BigBlueButtonURL use HTTPS.

    // This is the URL for the BigBlueButton server
    String BigBlueButtonURL = "https://bigbluebutton.example.com/bigbluebutton/";
    

    Finally, to apply all of the configuration changes made, you must restart all components of BigBlueButton:

    # bbb-conf --restart
    

    Test your HTTPS configuration

    In order to ensure you didn’t make any mistakes that could cause security compromises, please test your HTTPS configuration. A well-respected site that can do a series of automated tests is https://www.ssllabs.com/ssltest/ - simply enter your server’s hostname, optionally check the “Do not show results” check box if you would like to keep it private, then Submit.

    At time of writing, the configuration shown on this page should achieve an “A” ranking in the SSL Labs test page.

    Using Let’s Encrypt

    If you have a domain name assigned to your BigBlueButton server (i.e. bigbluebutton.example.com) and the server is on the Internet, then can use Let’s Encrypt to obtain a free SSL certificates.

    First, install Let’s Encrypt configuration tool. Please run all commands in this section root.

    # apt-get install letsencrypt
    

    Next, generate a set of 2048-bit diffie-hellman parameters to improve security for some types of ciphers.

    # mkdir /etc/nginx/ssl
    # openssl dhparam -out /etc/nginx/ssl/dhp-2048.pem 2048
    

    Before you can generate a certificate on your server, you need to configure BigBlueButton to use the intended hostname. If you have not already done so, use the following command (replace bigbluebutton.example.com with your own DNS name), to configure the BigBlueButton server with your hostname.

    # bbb-conf --setip bigbluebutton.example.com
    

    Next, request a SSL certificate from Let’s Encrypt using the letsencrypt tool. Again, replace bigbluebutton.example.com with your hostname.

    # letsencrypt --webroot -w /var/www/bigbluebutton-default/ -d bigbluebutton.example.com certonly
    
    IMPORTANT NOTES:
     - Congratulations! Your certificate and chain have been saved at
       /etc/letsencrypt/live/bigbluebutton.example.com/fullchain.pem. Your cert will
       expire on 20XX-YY-ZZ. To obtain a new version of the certificate in
       the future, simply run Let's Encrypt again.
     - If you like Let's Encrypt, please consider supporting our work by:
    
       Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
       Donating to EFF:                    https://eff.org/donate-le
    
    

    This will generate the following files

    # ls /etc/letsencrypt/live/bigbluebutton.example.com/
    cert.pem  chain.pem  fullchain.pem  privkey.pem
    

    Next, edit the nginx configuration file /etc/nginx/sites-available/bigbluebutton and add the marked lines below. Ensure that you’re using the correct filenames to match the certificate and key files you created above (again, replace bigbluebutton.example.com with your hostname).

    server {
      server_name bigbluebutton.example.com;
      listen 80;
      listen [::]:80;
      listen 443 ssl;
      listen [::]:443 ssl;
      ssl_certificate /etc/letsencrypt/live/bigbluebutton.example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/bigbluebutton.example.com/privkey.pem;
      ssl_session_cache shared:SSL:10m;
      ssl_session_timeout 10m;
      ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
      ssl_ciphers "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS:!AES256";
      ssl_prefer_server_ciphers on;
      ssl_dhparam /etc/nginx/ssl/dhp-2048.pem;
      

    The Let’s Encrypte certificates are good for 90 days and can be automatically renewed. To automatically request a renewal once a week, edit the crontab file for root.

    # sudo crontab -e
    

    And add the following two lines at the bottom:

    30 2 * * 1 /usr/bin/letsencrypt renew >> /var/log/le-renew.log
    35 2 * * 1 /bin/systemctl reload nginx
    

    These two directives will execute the letsencrypt-auto renew command every Monday at 2:30 am, and then reload Nginx at 2:35am (so the renewed certificate will be used). The output will be piped to a log file located at /var/log/le-renewal.log, so you can always check it later.

    To finish the SSL configuration, continue with the steps at Configure FreeSWITCH to user WebRTC.

    Configuring BigBlueButton behind a firewall

    Updating FreeSWITCH configuration

    As described in the introduction, a common setup is to have your BigBlueButton server behind a firewall (either virtual or physical). In this configuration, the network setup resembles the following diagram (yours would have different IP address of course).

    Install

    For WebRTC audio to work, you need to change the configuration of FreeSWITCH to listen for connections on the external IP address of the firewall. If you haven’t modified your firewall to forward ports to your BigBlueButton server, see configure a firewall.

    With the firewall configured to forward incoming connections to the BigBlueButton server, the next step is to configure FreeSWITCH to bind to the firewall’s external IP address.

    Edit the following files and substitute EXTERNAL_IP_ADDRESS for the external IP address (not the external hostname).

    Edit /opt/freeswitch/conf/vars.xml, and change

    <X-PRE-PROCESS cmd="set" data="external_rtp_ip=stun:stun.freeswitch.org"/>
    

    To

    <X-PRE-PROCESS cmd="set" data="external_rtp_ip=EXTERNAL_IP_ADDRESS"/>
    

    Change

    <X-PRE-PROCESS cmd="set" data="external_sip_ip=stun:stun.freeswitch.org"/>
    

    To

    <X-PRE-PROCESS cmd="set" data="external_sip_ip=EXTERNAL_IP_ADDRESS"/>
    

    Next, edit /opt/freeswitch/conf/sip_profiles/external.xml and change

        <param name="ext-rtp-ip" value="$${local_ip_v4}"/>
        <param name="ext-sip-ip" value="$${local_ip_v4}"/>
    

    to

        <param name="ext-rtp-ip" value="$${external_rtp_ip}"/>
        <param name="ext-sip-ip" value="$${external_sip_ip}"/>
    

    Next, edit /usr/share/red5/webapps/sip/WEB-INF/bigbluebutton-sip.properties, and make sure the values of bbb.sip.app.ip and freeswitch.ip have the internal IP address.

    bbb.sip.app.ip=<internal_ip>
    bbb.sip.app.port=5070
    
    freeswitch.ip=<internal_ip>
    freeswitch.port=5060
    

    Edit /etc/bigbluebutton/nginx/sip.nginx to connect to the external IP address.

    If you have configured SSL, use port 7443:

    location /ws {
            proxy_pass https://EXTERNAL_IP_ADDRESS:7443;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_read_timeout 6h;
            proxy_send_timeout 6h;
            client_body_timeout 6h;
            send_timeout 6h;
    }
    

    If you are not using SSL, use port 5066:

    location /ws {
            proxy_pass http://EXTERNAL_IP_ADDRESS:5066;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_read_timeout 6h;
            proxy_send_timeout 6h;
            client_body_timeout 6h;
            send_timeout 6h;
    }
    

    After making the above changes, restart BigBlueButton

    # bbb-conf --restart
    

    To test, launch FireFox and try connecting to your BigBlueButton server and join the audio. If you see the words ‘[ WebRTC Audio ]’ in the lower right-hand corner, it worked.

    If it didn’t work, there are two likely error messages when you try to connect with audio.

    Detected the following WebRTC issue: Error 1002: Could not make a WebSocket connection. Do you want to try Flash instead?

    ErrorDetected the following WebRTC issue Probable Cause
    1002: Could not make a WebSocket connection Note 1
    1007: ICE negotiation failed Note 2

    For Error 1002, check IP address for proxy_pass in /etc/bigbluebutton/nginx/sip.nginx is pointing to the external IP address of the firewall. Next, check that FreeSWITCH has started without errors

    # systemctl status freeswitch
    ● freeswitch.service - freeswitch
       Loaded: loaded (/lib/systemd/system/freeswitch.service; enabled; vendor preset: enabled)
       Active: active (running) since Fri 2017-03-03 23:13:07 UTC; 48min ago
      Process: 19349 ExecStart=/opt/freeswitch/bin/freeswitch -u freeswitch -g daemon -ncwait $DAEMON_OPTS (code=exited, status=0/SUCCESS)
     Main PID: 19361 (freeswitch)
        Tasks: 36
       Memory: 41.4M
          CPU: 20.744s
       CGroup: /system.slice/freeswitch.service
               └─19361 /opt/freeswitch/bin/freeswitch -u freeswitch -g daemon -ncwait -nonat
    
    Mar 03 23:13:05 t4 systemd[1]: Starting freeswitch...
    Mar 03 23:13:05 t4 freeswitch[19349]: 19361 Backgrounding.
    Mar 03 23:13:07 t4 freeswitch[19349]: FreeSWITCH[19349] Waiting for background process pid:19361 to be ready.....
    Mar 03 23:13:07 t4 freeswitch[19349]: FreeSWITCH[19349] System Ready pid:19361
    Mar 03 23:13:07 t4 systemd[1]: Started freeswitch.
    

    You should see active (running). If FreeSWITCH is not running, you can check it’s output log for clues on why it’s not running journalctl -u freeswitch.service. If you continue to see the Error 1002, check the diagnostic stops below, under Configure a dummy NIC.

    For Error 1007, it means that the web socket connect was successful (FreeSWITCH is running and received the request from the browser to setup a media path), but none of the IP/Port combinations returned by FreeSWITCH enabled the browser to connect and start transmitting media. To diagnose this error, open about:webrtc in FireFox and click ‘show details’ for the most recent connection. Look under the column Remote Candidate and check if you see the internal IP address of the BigBlueButton server. If so, you probably have a misconfiguration in the FreeSWITCH settings. Re-check against the examples shown above.

    If the correct IP address is shown, you probably have an issue where your firewall isn’t allowing UDP packets through in both directions on the required ports. Check your firewall documentation for help, or ask the BigBlueButton community mailing list.

    Configure a dummy NIC (if required)

    If you are encountering error 1002 when trying to connect to WebRTC audio, it might be that your firewall does not support “hairpin NAT”, which means when the BigBlueButton server connects to the firewall’s IP address, the firewall is not sending the connection right back.

    You can test if hairpin NAT is working using following command on your BigBlueButton server. Replace EXTERNAL_IP_ADDRESS with the external IP address of your firewall.

    # curl --trace-ascii - -k https://EXTERNAL_IP_ADDRESS:443/bigbluebutton/api
    

    Here’s the sample output from a success test.

    ~# curl --trace-ascii - -k https://203.0.113.1:443/bigbluebutton/api
    == Info:   Trying 203.0.113.1...
    == Info: Connected to 203.0.113.1 (203.0.113.1) port 443 (#0)
    == Info: found 173 certificates in /etc/ssl/certs/ca-certificates.crt
    == Info: found 692 certificates in /etc/ssl/certs
    == Info: ALPN, offering http/1.1
    == Info: SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256
    == Info:         server certificate verification SKIPPED
    == Info:         server certificate status verification SKIPPED
    == Info:         common name: HOSTNAME (does not match '203.0.113.1')
    == Info:         server certificate expiration date OK
    == Info:         server certificate activation date OK
    == Info:         certificate public key: RSA
    == Info:         certificate version: #3
    == Info:         subject: CN=bbb02.monasticeducation.net
    == Info:         start date: Fri, 24 Feb 2017 06:20:00 GMT
    == Info:         expire date: Thu, 25 May 2017 06:20:00 GMT
    == Info:         issuer: C=US,O=Let's Encrypt,CN=Let's Encrypt Authority X3
    == Info:         compression: NULL
    == Info: ALPN, server accepted to use http/1.1
    => Send header, 93 bytes (0x5d)
    0000: GET /bigbluebutton/api HTTP/1.1
    0021: Host: 203.0.113.1
    0035: User-Agent: curl/7.47.0
    004e: Accept: */*
    005b:
    <= Recv header, 17 bytes (0x11)
    ...
    <response><returncode>SUCCESS</returncode><version>1.0</version></response>== Info: Connection #0 to host 203.0.113.1 left intact
    

    You should see the <response>...</response> at the end.

    If you don’t see this, follow the steps below on your BigBlueButton server to setup a dummy NIC that has the same IP address as your firewall. Here’s a sample diagram of how it works.

    Install

    In this diagram, we’ve setup a dummy NIC for 203.0.113.1, which will allow FreeSWITCH to connect back to itself. This way, when FreeSWICH receives an internal connection from other parts of BigBlueButton, it will think that it’s on the external interface. This will cause it to use the correct IP address on the response.

    To setup a dummy NIC, on your BigBlueButton enter the following command and substitute EXTERNAL_IP_ADDRESS with the external IP address of your firewall.

    sudo ip addr add EXTERNAL\_IP\_ADDRESS/32 dev lo
    

    Next, check that the dummy NIC was created using the command ip addr.

    # ip addr
    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1
        link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
        inet 127.0.0.1/8 scope host lo
           valid_lft forever preferred_lft forever
        inet EXTERNAL_IP_ADDRESS/32 scope global lo
           valid_lft forever preferred_lft forever
        inet6 ::1/128 scope host
           valid_lft forever preferred_lft forever
    

    You should see the EXTERNAL_IP_ADDRESS for your firewall listed above.

    Next, edit /opt/freeswitch/conf/sip_profiles/external.xml and ensure the value for wss-binding uses the external IP address

    <param name="wss-binding"  value="EXTERNAL_IP_ADDRESS:7443"/>
    

    At this point, restart your BigBlueButton server with bbb-conf --restart, then try connecting to the WebRTC media again.

    Finally, to ensure this dummy NIC to be automatically created on restart, edit /etc/network/interfaces and add the following

    # The loopback network interface
    auto lo
    iface lo inet loopback
            post-up ip addr add EXTERNAL_IP_ADDRESS/32 dev lo
            pre-down ip addr del EXTERNAL_IP_ADDRESS/32 dev lo
    

    Upgrading BigBlueButton 1.1

    The BigBlueButton project is very active and follows a development process for each release.

    When upgrades are available for BigBlueButton (usually announced to bigbluebutton-dev), you can update your server with the following commands (replacing IP_or_hostname with the external hostname for your BigBlueButton server):

    sudo apt-get update
    sudo apt-get dist-upgrade
    
    sudo bbb-conf --setip <IP_or_hostname>
    sudo bbb-conf --check
    

    The use of sudo bbb-conf --setip will ensure that all configuration files are updated with the servers hostname (or IP address if you are not using a hostname for your server).

    Customization

    There are a number of post-setup configuration options to customize your BigBlueButton server for your needs.

    Modify the default landing page

    The default HTML landing page is located in

    /var/www/bigbluebutton-default/index.html
    

    Change this page to create your own landing page.

    Use the GreenLight front-end

    BigBlueButton comes with GreenLight, a simple front-end application that let’s users quickly and easily create meetings, invite others, join meetings, and manage the recordings.

    greenlight-start

    For more information see Installing GreenLight.

    Enable background music when only one person is in a session

    FreeSWITCH enabled you to have music play when only one users is in the voice conference. To enable background music, edit /opt/freeswitch/conf/autoload_configs/conference.conf.xml (as root).

    and around line 204 you’ll see the music on hold (moh-sound) commented out

    <!--
          <param name="moh-sound" value="$${hold_music}"/>
          <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
          <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
    -->
    

    and change it to

          <param name="moh-sound" value="$${hold_music}"/>
    <!--
          <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
          <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
    -->
    
    

    Then restart BigBlueButton

    # bbb-conf --restart
    

    and join an audio session. You should now hear music on hold if there is only one user in the session. You can also enable the enter/exit sounds as well in this manner.

    Add a phone number to the conference bridge

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

    Before you can configure FreeSWITCH to route the call to the right conference, you need to first obtain a phone number from a Internet Telephone Service Providers and configure FreeSWITCH accordingly to receive incoming calls via session initation protocol (SIP) from that provider..

    To route the incoming call to the correct BigBlueButton audio conference, you need to create a dialplan which, for FreeSWITCH, is a set of instructions that it runs when receiving an incoming call. When a user calls the phone number, the dialplan will prompt the user to enter a five digit number assocated with the conference.

    To create the dialplan, use the XML below and save it to /opt/freeswitch/conf/dialplan/public/my_provider.xml. Replace EXTERNALDID with the phone number phone number given to you by your Internet Telephone Service Provider (such as 6135551234).

    <extension name="from_my_provider">
     <condition field="destination_number" expression="^EXTERNALDID">
       <action application="answer"/>
       <action application="sleep" data="500"/>
       <action application="play_and_get_digits" data="5 5 3 7000 # conference/conf-pin.wav ivr/ivr-that_was_an_invalid_entry.wav pin \d+"/>
       <action application="transfer" data="SEND_TO_CONFERENCE XML public"/>
     </condition>
    </extension>
    <extension name="check_if_conference_active">
     <condition field="${conference ${pin} list}" expression="/sofia/g" />
     <condition field="destination_number" expression="^SEND_TO_CONFERENCE$">
       <action application="set" data="bbb_authorized=true"/>
       <action application="transfer" data="${pin} XML default"/>
     </condition>
    </extension>
    

    Change ownership of this file to freeswitch:daemon

    # chown freeswitch:daemon /opt/freeswitch/conf/dialplan/public/my_provider.xml
    

    and then restart FreeSWITCH:

    # systemctl restart freeswitch
    

    Try calling the phone number. It should connect to FreeSWITCH and you should hear a voice prompting you to enter the five digit PIN number for the conference.

    To show users the phone number along with the 5-digit PIN number within BigBlueButton, edit /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and change 613-555-1234 to the phone number provided by your Internet Telephone Service Provider

    #----------------------------------------------------
    # Default dial access number
    defaultDialAccessNumber=613-555-1234
    

    and change defaultWelcomeMessageFooter to

    defaultWelcomeMessageFooter=<br><br>To join this meeting by phone, dial:<br>  %%DIALNUM%%<br>Then enter %%CONFNUM%% as the conference PIN number.
    

    Save bigbluebutton.properties and restart BigBlueButton again. Each user that joins a session will see a message in the chat similar to.

    To join this meeting by phone, dial:
       613-555-1234
    and enter 12345 as the conference PIN number.
    

    Change the shared secret

    To validate incoming API calls, all external applications making API calls must checksum their API call using the same secret as configured in the BigBlueButton server.

    You’ll find the shared secret in /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties

    beans.dynamicConferenceService.securitySalt=<value_of_salt>
    

    To change the shared secret, do the following:

    1. Generate a new Universal Unique ID (UUID) from a UUID generator such as at http://www.somacon.com/p113.php. This will give a long string of random numbers that will be impossible to reverse engineer.
    2. Run the command sudo bbb-conf --setsecret new_secret.

    Note: If you have created you own front-end or are using a third-party plug-in to connect to BigBlueButton, its shared secret; otherwise, if the shared secrets do not match, the checksum for the incoming API calls will not match and the BigBlueButton server will reject the API call with an error.

    Increase the file size for an uploaded presentation

    The default maximum file upload size for an uploaded presentation is 30 MB.

    To increase this size, edit /var/www/bigbluebutton/client/conf/config.xml and edit maxFileSize` to the new value (note: if you have the development environment you need to edit ~/dev/bigbluebutton/bigbluebutton-client/src/conf/config.xml and then rebuild the client).

    Next, change the corresponding limit in nginx. Edit /etc/bigbluebutton/nginx/web.nginx and modify the value for client_max_body_size

           location /bigbluebutton {
               proxy_pass         http://127.0.0.1:8080;
               proxy_redirect     default;
               proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    
            # Allow 30M uploaded presentation document.
               client_max_body_size       30m;
    

    Restart BigBlueButton with sudo bbb-conf --restart. You should now be able to upload larger presentations within the new limit.

    Turn off the “comfort noise” noise when no one is speaking

    FreeSWITCH applies a “comfort noise”’” that is a slight background hiss to let users know they are still in a voice conference even when no one is talking (otherwise, they may forget they are connected to the conference bridge and say something unintended for others).

    If you want to remove the comfort noise, edit /opt/freeswitch/conf/autoload_configs/conference.conf.xml and change

    <param name="comfort-noise" value="true"/>
    

    to

    <param name="comfort-noise" value="false"/>
    

    Then restart BigBlueButton

    #  bbb-conf --restart
    

    Transfer existing published recordings

    If you want to do the minimum amount of work to quickly make your existing recordings on an older BigBlueButton server, transfer the contents of the /var/bigbluebutton/published and /var/bigbluebutton/unpublished directories. In addition, to preserve the backup of the original raw media, you should transfer the contents of the /var/bigbluebutton/recording/raw directory.

    Here is an example set of rsync commands that would accomplish this; run these on the new server to copy the files from the old server.

    $ rsync -rP root@old-bbb-server:/var/bigbluebutton/published/ /var/bigbluebutton/published/
    $ rsync -rP root@old-bbb-server:/var/bigbluebutton/unpublished/ /var/bigbluebutton/unpublished/
    $ rsync -rP root@old-bbb-server:/var/bigbluebutton/recording/raw/ /var/bigbluebutton/recording/raw/
    

    Other methods of transferring these files can also be used; for example, you could create a tar archive of each of the directories, and transfer it via scp, or use a shared NFS mount.

    You will then need to fix the permissions on the newly copied recordings:

    chown -R tomcat7:tomcat7 /var/bigbluebutton/published /var/bigbluebutton/unpublished /var/bigbluebutton/recording/raw
    

    If the recordings were copied from a server with a different hostname, you will have to run the following command to fix the stored hostnames. (If you don’t do this, it’ll either return a 404 error, or attempt to load the recordings from the old server instead of the new server!)

    Note that this command will restart the BigBlueButton server, interrupting any live sessions.

    $ bbb-conf --setip <ip_address_or_hostname>
    

    For example,

    $ bbb-conf --setip bigbluebutton.example.com
    

    The transferred recordings should be immediately visible via the BigBlueButton recordings API.

    Re-process raw recordings

    This is the recommended way of copying recordings, since the recordings will be rebuilt using newer versions of the recording software, enabling new features and fixing bugs that may have been present with the old version. The downside is that this can take a long time, and will use a lot of CPU on your new BigBlueButton server while you wait for the recordings to process.

    If your old server has all of the original recording files in the /var/bigbluebutton/recording/raw directory, then you can transfer these files to the new server, for example with rsync:

    This example rsync command could be run on the new server, and will copy the recording file from the old server.

    $ rsync -rP root@old-bbb-server:/var/bigbluebutton/recording/raw/ /var/bigbluebutton/recording/raw/
    

    There are other ways of transferring these files; for example, you could create a tar archive of the /var/bigbluebutton/recording/raw directory, and copy it with scp, or use a shared NFS mount. Any method should work fine.

    You will then need to fix the permissions on the newly copied recordings:

    $ chown -R tomcat7:tomcat7 /var/bigbluebutton/recording/raw
    

    And initiate the recording re-processing

    $ bbb-record --rebuildall
    

    The BigBlueButton server will automatically go through the recordings and rebuild and publish them. You can use the bbb-record --watch command to see the progress.

    Install callback for events (webhooks)

    Want to receive callbacks to your application when an event occurs in BigBlueButton? BigBlueButton provides an optional web hooks package that installs a node.js application listens for all events on BigBlueButton and sends POST requests with details about these events to hooks registered via an API. A hook can be any external URL that can receive HTTP POST requests.

    To install bbb-webhooks

    # apt-get install bbb-webhooks
    

    For information on cofiguring bbb-webhooks, see bbb-webhooks.

    Change the default presentation

    When a new meeting starts, BigBlueButton displays a default presentation. The file for the default presentation is located in /var/www/bigbluebutton-default/default.pdf. You can replace the contents of this file with your presentation. Whenever a meeting is created, BigBlueButton will automatically load, convert, and display this presentation for all users.

    Alternatively, you can change the global default by editing /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and changing the URL for beans.presentationService.defaultUploadedPresentation.

    # Default Uploaded presentation file
    beans.presentationService.defaultUploadedPresentation=${bigbluebutton.web.serverURL}/default.pdf
    

    You’ll need to restart BigBlueButton after the change with sudo bbb-conf --restart.

    If you want to specify the default presentation for a given meeting, you can also pass a URL to the presentation as part of the create meeting API call.

    Change the default welcome message

    The default welcome message is built from three parameters: two system-wide parameters (see below) and the welcome parameter from the BigBlueButton create API call.

    You’ll find the two system-wide welcome parameters defaultWelcomeMessage and defaultWelcomeMessageFooter in /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties.

    defaultWelcomeMessage=<default welcome message>
    defaultWelcomeMessageFooter=<default welcome message footer>
    

    When a front-end creates a BigBlueButton session, it may also pass a welcome parameter in the create API call.

    The final welcome message shown to the user (as blue text in the Chat window) is a composite of welcome + defaultWelcomeMessage + defaultWelcomeMessageFooter.

    The welcome message is fixed for the duration of a meeting. If you want to see the effect of changing the welcome parameter, you must end the current meeting or wait until the BigBlueButton server removes it from memory (which occurs about two minutes after the last person has left). If you change the parameters in bigbluebutton.properties, you must restart BigBlueButton with sudo bbb-conf --restart for the new values to take effect.

    Change the default locale

    By default, the BigBlueButton client should detect the browser’s locale and use that default language accordingly. The default language is English, but you can change that by editing bigbluebutton/client/BigBlueButton.html and change the value

    localeChain = "en_US";
    

    You can see the list of languages installed with BigBlueButton in the directory /var/www/bigbluebutton/client/locale/.

    Change the video quality of the shared webcams

    The setting for picture quality of the webcams is in the videoconf module.

    In most cases, you can leave the default settings. However, you can specify the Flash player use the maximum amount of bandwidth (camQualityBandwidth="0") to show a picture of ninety percent quality (camQualityPicture="90").

    camQualityPicture="70"
    

    To reduce the quality of the picture (and increase the frame rate), lower the value of camQualityPicture. Corresponding, to increase the quality of the picture (and reduce the frame rate), increase the value of camQualityPicture.

    However, as camQualityPicture is already ninety percent, you’ll find that slight increases are not very noticeable in picture quality, but do decrease the frame rate.

    You can change the video quality through the client’s config.xml file, by default located in /var/www/bigbluebutton/client/conf. Scroll down to the entry named VideoconfModule. The value of the videoQuality attribute can be anywhere from 0 to 100. 0 means priority is given to the bandwidth and if bandwidth is low, quality will suffer. Quality of 100 means no video compression will be done at all, and you will get maximum quality at the expense of bandwidth. If the bandwidth is low, the frame rate will suffer.

    For more information see Client Configuration.

    Change the /client/BigBlueButton.html portion of the URL

    Using nginx, you can rewrite the incoming URL for /client/BigBlueButton.html to appear as a different link, such as /conference/.

    First, modify /etc/bigbluebutton/nginx/client.nginx and comment out the following section:

            # BigBlueButton.html is here so we can expire it every 1 minute to
            # prevent caching.
            #location /client/BigBlueButton.html {
            #        root    /var/www/bigbluebutton;
            #        index  index.html index.htm;
            #        expires 1m;
            #}
    

    Next, create the file /etc/bigbluebutton/nginx/rewrite.nginx with the following contents:

    location /client/BigBlueButton.html {
            rewrite ^ /conference permanent;
    }
    
    location /conference {
            alias  /var/www/bigbluebutton/client;
            index BigBlueButton.html;
            expires 1m;
    }
    

    Finally, restart nginx with the following command:

       sudo systemctl restart nginx
    

    Now login to the demo page and you’ll see the URL now shows /conference/ instead of /client/BigBlueButton.html.

    Always record every meeting

    By default, the BigBlueButton server will produce a recording when (1) the meeting has been created with record=true in the create API call and (2) a moderator has clicked the Start/Stop Record button (at least once) during the meeting.

    However, you can configure a BigBlueButton server to record every meeting, edit /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and change

    # Start recording when first user joins the meeting.
    # For backward compatibility with 0.81 where whole meeting
    # is recorded.
    autoStartRecording=false
    
    # Allow the user to start/stop recording.
    allowStartStopRecording=true
    

    to

    # Start recording when first user joins the meeting.
    # For backward compatibility with 0.81 where whole meeting
    # is recorded.
    autoStartRecording=true
    
    # Allow the user to start/stop recording.
    allowStartStopRecording=false
    

    To apply the changes, restart the BigBlueButton server using the command

    sudo bbb-conf --restart
    

    Increase the 200 page limit for uploads

    BigBlueButton, by default, restricts uploads to 200 pages. To increase this value, open /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and change the maxNumPages value:

    #----------------------------------------------------
    # Maximum number of pages allowed for an uploaded presentation (default 200).
    maxNumPages=200
    

    After you save the changes to bigbluebutton.properties, restart the BigBlueButton server with

    sudo bbb-conf --restart
    

    Restrict webcam sharing to the presenter

    You can configure all metings to restrict sharing of webcam to only the current presenter. To do so, open config.xml in the parameters for videomodule, change the following:

    presenterShareOnly="false"
    

    to

    presenterShareOnly="true"
    

    Turn off “you are now muted”

    You can remove this sound for all users by editing /opt/freeswitch/etc/freeswitch/autoload_configs/conference.conf.xml and moving the lines containing muted-sound and unmuted-sound into the commented section.

        <profile name="cdquality">
          <param name="domain" value="$${domain}"/>
          <param name="rate" value="48000"/>
          <param name="interval" value="20"/>
          <param name="energy-level" value="100"/>
          <!-- <param name="sound-prefix" value="$${sounds_dir}/en/us/callie"/> -->
          <param name="muted-sound" value="conference/conf-muted.wav"/>
          <param name="unmuted-sound" value="conference/conf-unmuted.wav"/>
          <param name="alone-sound" value="conference/conf-alone.wav"/>
    <!--
          <param name="moh-sound" value="$${hold_music}"/>
          <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
          <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
    -->
          <param name="kicked-sound" value="conference/conf-kicked.wav"/>
          <param name="locked-sound" value="conference/conf-locked.wav"/>
          <param name="is-locked-sound" value="conference/conf-is-locked.wav"/>
          <param name="is-unlocked-sound" value="conference/conf-is-unlocked.wav"/>
          <param name="pin-sound" value="conference/conf-pin.wav"/>
          <param name="bad-pin-sound" value="conference/conf-bad-pin.wav"/>
          <param name="caller-id-name" value="$${outbound_caller_name}"/>
          <param name="caller-id-number" value="$${outbound_caller_id}"/>
          <param name="comfort-noise" value="true"/>
    
          <!-- <param name="conference-flags" value="video-floor-only|rfc-4579|livearray-sync|auto-3d-position|minimize-video-encoding"/> -->
    
          <!-- <param name="video-mode" value="mux"/> -->
          <!-- <param name="video-layout-name" value="3x3"/> -->
          <!-- <param name="video-layout-name" value="group:grid"/> -->
          <!-- <param name="video-canvas-size" value="1920x1080"/> -->
          <!-- <param name="video-canvas-bgcolor" value="#333333"/> -->
          <!-- <param name="video-layout-bgcolor" value="#000000"/> -->
          <!-- <param name="video-codec-bandwidth" value="2mb"/> -->
          <!-- <param name="video-fps" value="15"/> -->
    
        </profile>
    

    Troubleshooting

    This section will help you resolve common errors with installation of BigBlueButton. If you are unable to resolve any installation issues, post a description of the error message along with the version of BigBlueButton you are installing to bigbluebutton-setup and the community can help you further.

    Run sudo bbb-conf –check

    We’ve built in a BigBlueButton configuration utility, called bbb-conf, to help you configure your BigBlueButton server and troubleshoot your setup if something doesn’t work right.

    If you think something isn’t working correctly, the first step is enter the following command.

    $ sudo bbb-conf --check
    

    This will check your setup to ensure the correct processes are running, the BigBlueButton components have correctly started, and look for common configuration problems that might prevent BigBlueButton from working properly.

    If you see text after the line ** Potential problems described below **, then it may be warnings (which you can ignore if you’ve change settings) or errors with the setup.

    Could not get your microphone for a WebRTC call

    Chrome requires (As of Chrome 47) that to access the user’s microphone for WebRTC your site must be serving pages via HTTPS (that is, nginx is configured with a SSL certificate).

    If the user attempts to share their microphone and your BigBlueButton sever is not configured for SSL, Chrome will block access and BigBlueButton will report the following error

    WebRTC Audio Failure: Detected the following WebRTC issue: Could not get your microphone for a WebRTC call. Do you want to try flash instead?

    To enable Chrome to access the user’s microphone, see Configuring HTTPS on BigBlueButton.

    Tomcat7 takes a long time to startup

    Tomcat relies on the SecureRandom class (which uses available entropy) to provide random values for its session IDs. On a virtualized server, however, the available entropy can run low and cause tomcat7 to block for a long period before it finishes it’s startup sequence (see Tomcat Entropy Source).

    To provide tomcat7 with more entropy, you can install haveged

    $ sudo apt-get install haveged
    

    For more information see How to Setup Additional Entropy for Cloud Servers Using Haveged.

    Errors with packages

    Some hosting providers do not provide a complete /etc/apt/source.list. If you are finding your are unable to install a package, try replacing your /etc/apt/sources.list with the following

    deb http://archive.ubuntu.com/ubuntu xenial main restricted universe multiverse
    deb http://archive.ubuntu.com/ubuntu xenial-updates main restricted universe multiverse
    deb http://security.ubuntu.com/ubuntu xenial-security main restricted universe multiverse
    

    then do

    $ sudo apt-get update
    

    and try installing BigBlueButton again from the beginning.

    Welcome to nginx

    During installation of BigBlueButton the packaging scripts attempt to assign the correct IP address during setup. However, if the IP address changes (such as when rebooting a VM), or the first IP address was not the correct IP address for the server, you may see a “Welcome to nginx” page.

    To reconfigure the BigBlueButton to use the correct IP address or hostname, see BigBlueButton does not load.

    BigBlueButton does not load

    If your has changed it’s network connection (such as on reboot), you can most of BigBlueButton’s configuration files with the following steps.

    $ sudo bbb-conf --setip <ip_address_or_hostname>
    
    $ sudo bbb-conf --clean
    $ sudo bbb-conf --check
    

    For more information see bbb-conf options.

    Conference not found errors

    The command sudo bbb-conf --debug searches through the red5, tomcat7, and nginx logs looking for errors and exceptions. However, the messages such as

        -- ERRORS found in /usr/share/red5/log/* --
    /usr/share/red5/log/bigbluebutton.log:2015-05-02 13:50:37,681-04:00 [pool-17-thread-1] ERROR o.b.w.v.f.a.PopulateRoomCommand - Not XML: [Conference 78505 not found]
    

    are innocious and can be ignored.

    If you’ve installed/uninstalled BigBlueButton packages, you may get a No Symbolic Link warning from bbb-conf --check:

    ** Potential Problems **
        nginx (conf): no symbolic link in /etc/nginx/sites-enabled for bigbluebutton
    

    To solve this, add a symbolic link to nginx for the BigBlueButton site:

    $ sudo ln -s /etc/nginx/sites-available/bigbluebutton /etc/nginx/sites-enabled/bigbluebutton
    $ sudo /etc/init.d/nginx restart
    

    Users not able to join Listen Only mode

    When doing sudo bbb-conf --check, you may see the warning

    voice Application failed to register with sip server
    

    This error occurs when bbb-apps-sip isn’t able to make a SIP call to FreeSWITCH. You’ll see this in BigBlueButton when users click the headset icon and don’t join the voice conference.

    One possible cause for this is you have just installed BigBlueButton, but not restarted it. The packages do not start up the BigBlueButton components in the right order. To restart BigBlueButton, do the following:

    $ sudo bbb-conf --restart
    $ sudo bbb-conf --check
    

    If you don’t want FreeSWITCH to bind to 127.0.0.1, you need to figure out which IP address its using. First, determine the IP address FreeSWITCH is monitoring for incoming SIP calls with the following command:

    $ netstat -ant | grep 5060
    

    You should see an output such as

    tcp        0      0 234.147.116.3:5060    0.0.0.0:*               LISTEN
    

    In this example, FreeSWITCH is listening on IP address 234.147.116.3. The IP address on your server will be different.

    Next, edit /usr/share/red5/webapps/sip/WEB-INF/bigbluebutton-sip.properties and set the value for sip.server.host to the IP address returned from the above command. Save the changes (you’ll need to edit the file as root to save changes).

    Restart BigBlueButton using the commands and run the built-in diagnostics checks.

    $ sudo bbb-conf --clean
    $ sudo bbb-conf --check
    

    Client WebRTC Error Codes

    WebRTC offers very high-quality audio. However, the user’s network settings (or firewall) may not allow WebRTC to connect (or keep connected).

    Here are the following lists the possible WebRTC error messages that a user may encounter:

    • 1001: WebSocket disconnected - The WebSocket had connected successfully and has now disconnected. Possible Causes:
      • Loss of internet connection
      • Nginx restarting can cause this
    • 1002: Could not make a WebSocket connection - The initial WebSocket connection was unsuccessful. Possible Causes:
      • Firewall blocking ws protocol
      • Server is down or improperly configured
    • 1003: Browser version not supported - Browser doesn’t implement the necessary WebRTC API methods. Possible Causes:
      • Out of date browser
    • 1004: Failure on call - The call was attempted, but failed. Possible Causes:
      • For a full list of causes refer here, http://sipjs.com/api/0.6.0/causes/
      • There are 24 different causes so I don’t really want to list all of them
    • 1005: Call ended unexpectedly - The call was successful, but ended without user requesting to end the session. Possible Causes:
      • Unknown
    • 1006: Call timed out - The library took too long to try and connect the call. Possible Causes:
      • Previously caused by Firefox 33-beta on Mac. We’ve been unable to reproduce since release of FireFox 34
    • 1007: ICE negotiation failed - The browser and FreeSWITCH try to negotiate ports to use to stream the media and that negotiation failed. Possible Causes:
      • NAT is blocking the connection
      • Firewall is blocking the UDP connection/ports
    • 1008: Call transfer failed - A timeout while waiting for FreeSWITCH to transfer from the echo test to the real conference. This might be caused by a misconfiguration in FreeSWITCH, or there might be a media error and the DTMF command to transfer didn’t go through (In this case, the voice in the echo test probably didn’t work either.)
    • 1009: Could not fetch STUN/TURN server information - This indicates either a BigBlueButton bug (or you’re using an unsupported new client/old server combination), but could also happen due to a network interruption.
    • 1010: ICE negotiation timeout - After the call is accepted the client’s browser and the server try and negotiate a path for the audio data. In some network setups this negotiation takes an abnormally long time to fail and this timeout is set to avoid the client getting stuck.

    Not running: nginx

    The common reasons for nginx not running are inability to bind to port 80 and configuration errors. To check if port 80 is already in use, use

    $ sudo netstat -ant
    

    to see if any process is currently bound to port 80. If so, check to see if another web server is installed. If so, then stop the web server and try to restart nginx. One of the server requirements before you install BigBlueButton is that port 80 is not in use by another application (such as Apache). For details on why this is a requirements, see We recommend running BigBlueButton on port 80.

    If port 80 is free, check if your nginx configuration file has errors. Try a restart of nginx

    $ sudo systemctl restart nginx
    

    and look for the output of

       [ OK ]
    

    If you see [ Fail ], then your nginx configuration files might have a syntax error. Check the syntax of the nginx configuration files using the command

    $ sudo nginx -t
    

    and see if it repots any errors. You can also check the error.log file for nginx to see what errors it gives on startup

    $ sudo cat /var/log/nginx/error.log
    

    Running within an LXD Container

    LXD is a very powerful container system for Ubuntu lets you run full Ubuntu 16.04 servers within a container. Because you can easily clone and snapshot LXD containers, they are ideal for development and testing of BigBlueButton.

    However, if you install BigBlueButton within an LXD container, you will get the following error from sudo bbb-conf --check

    ** Potential problems described below **
    
    #
    # Error: Unable to connect to the FreeSWITCH Event Socket Layer on port 8021
    

    You’ll also get an error from starting FreeSWITCH with bbb-conf --restart. When you try systemctl status freeswitch.service, you’ll see an error with SETSCHEDULER.

    # systemctl status freeswitch.service
    ● freeswitch.service - freeswitch
       Loaded: loaded (/lib/systemd/system/freeswitch.service; enabled; vendor preset: enabled)
       Active: inactive (dead) (Result: exit-code) since Wed 2017-04-26 16:34:24 UTC; 23h ago
      Process: 7038 ExecStart=/opt/freeswitch/bin/freeswitch -u freeswitch -g daemon -ncwait $DAEMON_OPTS (code=exited, status=214/SETSCHEDULER)
    
    Apr 26 16:34:24 big systemd[1]: Failed to start freeswitch.
    Apr 26 16:34:24 big systemd[1]: freeswitch.service: Unit entered failed state.
    Apr 26 16:34:24 big systemd[1]: freeswitch.service: Failed with result 'exit-code'.
    Apr 26 16:34:24 big systemd[1]: freeswitch.service: Service hold-off time over, scheduling restart.
    Apr 26 16:34:24 big systemd[1]: Stopped freeswitch.
    Apr 26 16:34:24 big systemd[1]: freeswitch.service: Start request repeated too quickly.
    Apr 26 16:34:24 big systemd[1]: Failed to start freeswitch.
    

    This error occurs because the default systemd unit script for FreeSWITCH tries to run with permissions not available to the LXD container. To run FreeSWITCH within an LXD container, edit /lib/systemd/system/freeswitch.service and replace with the following

    [Unit]
    Description=freeswitch
    After=syslog.target network.target local-fs.target
    
    [Service]
    Type=forking
    PIDFile=/opt/freeswitch/var/run/freeswitch/freeswitch.pid
    Environment="DAEMON_OPTS=-nonat"
    EnvironmentFile=-/etc/default/freeswitch
    ExecStart=/opt/freeswitch/bin/freeswitch -u freeswitch -g daemon -ncwait $DAEMON_OPTS
    TimeoutSec=45s
    Restart=always
    WorkingDirectory=/opt/freeswitch
    User=freeswitch
    Group=daemon
    
    [Install]
    WantedBy=multi-user.target
    

    Then enter the following commands to load the new unit file and restart BigBlueButton.

    # sudo systemctl daemon-reload
    # sudo bbb-conf --restart
    

    You can run BigBlueButton within a LXD container.

    Root partition too small

    If the root partition on your BigBlueButton server is too small (for disk space requirements see Before you install), we recommend moving the following directories to an external partition with sufficient disk space.

    BigBlueButton processing and storage of recordings:

      /var/bigbluebutton
    

    FreeSWITCH recording of audio files:

      /var/freeswitch/meetings
    

    And red5 recording of video files:

      /usr/share/red5/webapps/video/streams
    

    To make the move, we’ll first stop BigBlueButton, then move the above directories to a new location on the external partition, create symbolic links from the original locations to the new locations, and restart BigBlueButton.

    In the following example, the external partition is mounted on /mnt.

    $ sudo bbb-conf --stop
    
    $ sudo mv /opt/freeswitch/recordings /mnt
    $ sudo ln -s /mnt/recordings /opt/freeswitch/recordings
    
    $ sudo mv /usr/share/red5/webapps/video/streams /mnt
    $ sudo ln -s /mnt/streams /usr/share/red5/webapps/video/streams
    
    $ sudo /var/bigbluebutton /mnt
    $ sudo ln -s /mnt/bigbluebutton /var/bigbluebutton
    
    $ sudo bbb-conf --start
    

    Unable to create presentation

    If you see the following error in /var/bigbluebutton/bbb-web.log

      failed to map segment from shared object: Operation not permitted
    

    use the command mount to check that the /tmp director does not have noexec permissions (which would prevent executables from running in the /tmp directory). If you see noexec for /tmp, you need to remount the directory with permissions that enable processes (such as the slide conversion) to execute in the /tmp directory.

    Forward calls from an Asterisk server to FreeSWITCH

    Let’s assume the following:

    asterisk server ip:          192.168.1.100
    bigbluebutton/freeswitch ip: 192.168.1.200
    

    Changes to your Asterisk server

    Setup your gateway to BigBlueButton/FreeSWITCH. in /etc/asterisk/sip.conf add

    [fs-gw]
    type=peer
    username=fs-gw
    insecure=very
    contactpermit=192.168.1.200/255.255.255.255
    qualify=no
    nat=yes
    host=192.168.1.200
    canreinvite=no
    disallow=all
    allow=ulaw
    

    Route the calls to the gateway. In /etc/asterisk/extensions.conf context where your calls are being handled, forward the calls to the gateway. Here, when someone dials 85001, the call is sent to the fs-gw defined above.

    exten => 85001,1,Dial(SIP/fs-gw/${EXTEN})
    exten => 85001,2,Hangup
    

    Changes to your BigBlueButton/FreeSWITCH server

    In BigBlueButton/FreeSWITCH, make the following changes:

    Lock down so that only Asterisk can forward calls to FreeSWITCH. In /opt/freeswitch/conf/autoload_configs/acl.conf.xml, add the following ACL. We also need to allow BigBlueButton to call into FreeSWITCH, that’s why we add the IP of BigBlueButton/FreeSWITCH into the ACL.

        <list name="asterisk-gw" default="deny">
           <node type="allow" cidr="192.168.1.200/32"/>
           <node type="allow" cidr="192.168.1.100/32"/>
           <node type="allow" cidr="127.0.0.1/32"/>
        </list>
    

    Then we apply the ACL into the profile that receives the calls from external gateways. In /opt/freeswitch/conf/sip_profiles/external.xml, add the ACL under <settings>

      <settings>
        <!-- Apply ACL from asterisk-gw -->
        <param name="apply-inbound-acl" value="asterisk-gw"/>
    ...
    </settings>
    

    To debug, try connecting to FS CLI and increase logging level. Once connected, make your call and see what the logs say.

      cd /opt/freeswitch/bin
      ./fs_cli
    
      Once connected:
      help -- shows the available commands
      console loglevel <level> -- change log level
    
      Ctrl-D to exit
    

    FreeSWITCH fails to bind to port 8021

    FreeSWITCH supports both IPV4 and IPV6. However, if your server does not support IPV6, FreeSWITCH will be unable to bind to port 8021. If you run sudo bbb-conf --check and see the following error

    # Error: Found text in freeswitch.log:
    #
    #    Thread ended for mod_event_socket
    #
    # FreeSWITCH may not be responding to requests on port 8021 (event socket layer)
    # and users may have errors joining audio.
    #
    

    it might be that your server has IPV6 disabled (or does not support it). You can check this by running the following command

    $ sudo ip addr | grep inet6
    inet6 ::1/128 scope host
    ...
    

    If you do not see the line inet6 ::1/128 scope host, then your server has IPV6 disabled. In this case, we need to disable FreeSWITCH’s support for IPV6. First, edit /opt/freeswitch/etc/freeswitch/autoload_configs/event_socket.conf.xml and change the line

        <param name="listen-ip" value="::"/>
    

    to

        <param name="listen-ip" value="127.0.0.1"/>
    

    This tells FreeSWITCH that instead of binding port 8021 to the local IPV6 address, bind to the IPV4 address 127.0.0.1. Next, execute the following two commands

    $ sudo mv /opt/freeswitch/etc/freeswitch/sip_profiles/internal-ipv6.xml /opt/freeswitch/etc/freeswitch/sip_profiles/internal-ipv6.xml_
    $ sudo mv /opt/freeswitch/etc/freeswitch/sip_profiles/external-ipv6.xml /opt/freeswitch/etc/freeswitch/sip_profiles/external-ipv6.xml_
    

    and then restart BigBlueButton with the commands

    sudo bbb-conf --clean
    sudo bbb-conf --check
    

    FneeSWITCH fails to start with a SETSCHEDULER error

    When running in a container (like a chroot, OpenVZ or LXC), it might not be possible for FreeSWITCH to set the CPU priority and other tasks is not possible.

    If you see an error starting FreeSWITCH, try running systemctl status freeswitch.service and see if you see the error related to SETSCHEDULER

    # systemctl status freeswitch.service
    ● freeswitch.service - freeswitch
       Loaded: loaded (/lib/systemd/system/freeswitch.service; enabled; vendor preset: enabled)
       Active: inactive (dead) (Result: exit-code) since Mon 2017-10-02 16:17:29 UTC; 18s ago
      Process: 10967 ExecStart=/opt/freeswitch/bin/freeswitch -u freeswitch -g daemon -ncwait $DAEMON_OPTS (code=exited, status=214/SETSCHEDULER)
     Main PID: 3327 (code=exited, status=0/SUCCESS)
    
    Oct 02 16:17:29 scw-9e2305 systemd[1]: Failed to start freeswitch.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: freeswitch.service: Unit entered failed state.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: freeswitch.service: Failed with result 'exit-code'.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: freeswitch.service: Service hold-off time over, scheduling restart.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: Stopped freeswitch.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: freeswitch.service: Start request repeated too quickly.
    Oct 02 16:17:29 scw-9e2305 systemd[1]: Failed to start freeswitch.
    

    If so, then edit /lib/systemd/system/freeswitch.service and comment out the line containing CPUSchedulingPolicy

    IOSchedulingPriority=2
    #CPUSchedulingPolicy=rr
    CPUSchedulingPriority=89
    

    Then do systemctl daemon-reload and restart BigBlueButton. FreeSWITCH should now startup without error.

    Connect BigBlueButton to an external FreeSWITCH Server

    BigBlueButton bundles in FreeSWITCH, but you can configure BigBlueButton to use an external FreeSWITCH server.

    First, edit /usr/share/red5/webapps/bigbluebutton/WEB-INF/bigbluebutton.properties

    freeswitch.esl.host=127.0.0.1
    freeswitch.esl.port=8021
    freeswitch.esl.password=ClueCon
    

    Change freeswitch.esl.host to point to your external FreeSWITCH IP address. Change the default freeswitch.esl.password to the ESL password for your server.

    You can use http://strongpasswordgenerator.com/ to generate passwords.

    In your external FreeSWITCH server, edit /opt/freeswitch/conf/autoload_configs/event_socket.conf.xml.

    <configuration name="event_socket.conf" description="Socket Client">
      <settings>
        <param name="nat-map" value="false"/>
        <param name="listen-ip" value="127.0.0.1"/>
        <param name="listen-port" value="8021"/>
        <param name="password" value="ClueCon"/>
        <!-- param name="apply-inbound-acl" value="localnet.auto"/ -->
      </settings>
    </configuration>
    

    Change the listen-ip to your external FreeSWITCH server IP and also change the password to be the same as freeswitch.esl.password.

    Edit /usr/share/red5/webapps/sip/WEB-INF/bigbluebutton-sip.properties

    bbb.sip.app.ip=127.0.0.1
    bbb.sip.app.port=5070
    
    sip.server.username=bbbuser
    sip.server.password=secret
    
    freeswitch.ip=127.0.0.1
    freeswitch.port=5060
    

    Change bbb.sip.app.ip to your BigBlueButton server ip.

    Change sip.server.password to something else.

    Change freeswitch.ip to your external FreeSWITCH ip.

    In your external FreeSWITCH server.

    Edit /opt/freeswitch/conf/directory/default/bbbuser.xml

      <user id="bbbuser">
        <params>
          <!-- omit password for authless registration -->
          <param name="password" value="secret"/>
          <!-- What this user is allowed to access -->
          <!--<param name="http-allowed-api" value="jsapi,voicemail,status"/> -->
        </params>
    

    Change password to match the password you set in sip.server.password.

    Older versions

    If you want to install BigBlueButton 1.0, here are the links

    If you want to install BigBlueButton 0.9, here are the links