Welcome to the installation guide for BigBlueButton 2.0. This document is for system administrators and developers wanting to install and configure there own BigBlueButton server.

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

    To achieve this goal, BigBlueButton offers real-time sharing of audio, video, slides, and the presenter’s screen. For enagement, it offers chat, emoji, polling, multi-user whiteboard, breakout rooms, and shared notes. For details of the features, see overview of BigBlueButton.

    This release includes the HTML5 client for mobile users. The HTML5 client implements all features of the Flash client for viewers except two-way webcams (which is coming in a future update). All the remaining viewer capabilities – such as participating in multi-user whiteboard, breakout rooms, and polling – is implemented along with high-quality WebRTC audio.

    For system administrators, this document covers installation of BigBlueButton on a Ubuntu 16.04 64-bit server, configuring it to use a hostname and SSL certificate, and, if the server is running behind a firewall, configuring the firewall to pass through specific ports to the BigBlueButton server.

    For developers, you may opt to install BigBlueButton on a local VM or LXC container. In such a setup, you don’t need to configure it with a hostname or SSL certiicate. In such cases, FireFox to access your server as it doesn’t require a SSL cerificate to use web real-time commications (WebRTC).

    If you encounter difficulties with the installation, check out the troubleshooting guide at the end of this document.

    If you can’t resolve the issue, see http://bigbluebutton.org/support for how to post a message to our bigbluebutton-setup mailing list. When you post for help, the more information you give the easier it is for others to help. Be sure to post:

    • the version of BigBlueButton you are trying to install,
    • any errors your received during installation, and
    • the error you are receiving.

    All the core BigBlueButton developers hang out in this form and will attempt to help you if you get stuck.

    Before you install

    Before jumping ahead to installation steps, give youself a moment to go through this section to make sure your server meets the minimum requirements. Doing so will save you time later on.

    Minimum server requirements

    We recommend installing BigBlueButton on a ‘clean’ Ubuntu 16.04 64-bit server. The server should not have any have web applications installed (such as plesk or Apache2). Such applications want to bind to port 80 and causes subtle conflicts with the installation and running of BigBlueButton that are difficult to resolve.

    Specifically, the minimum server requirements for installing BigBlueButton 2.0 are

    • Ubuntu 16.04 64-bit OS running Linux kernel 4.x
    • 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

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

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

    If you want to install BigBlueButton on Amazon EC2, we recommend running BigBlueButton on a c5.xlarge (or greater CPU) instance. These newer compute instensive instances offer very close to bare-metal performance.

    What about bandwidth for your end 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.

    Pre-installation checks

    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. Again, taking a few moments with these checks will save you time later on.

    First, check that the locale of the server is en_US.UTF-8. Enter the following command and ensure 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", 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.

    Next, check that your server is running Linux 4.x.

    $ uname -r
    4.15.0-38-generic
    

    Next, let’s check the number of CPU cores your server has

    $ cat /proc/cpuinfo | awk '/^processor/{print $3}' | wc -l
    4
    

    and confirm the result is 4 (or higher).

    Note: BigBlueButton will not run on a 2.6 Kernel (such as Linux 2.6.32-042stab133.2 on x86_64 on OpenVZ VPS).

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

    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 and can use FireFox to access it, 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 the 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 there are many options, see obtain an SSL certificate.

    Configure the firewall (if required)

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

    The easiest network configuration for installing BigBlueButton is on a server that 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 and 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 TCP/UDP 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.

    Configure 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 (this will save you time later on if you encounter issues).

    Testing the firewall

    To test connections on various ports needed by BigBlueButton, you will use a tool called netcat to listen for connections. You’ll use netcat on the BigBlueButton server and on external server (outside the firewall) to generate connections. If the connections test fail, then the firewall is forwarding the packets.

    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. This frees up the ports we want to test. 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. Replace 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
    

    Again, 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
    

    Installation

    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 (or intend to obtain one with Lets Encrypt)

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

    At this point, your ready to install. You have two options:

    • Option #1: Use bbb-install.sh to install pretty much everything you’ll need with a single command (this is recommended if it’s your first time setting up BigBlueButton)
    • Go through the step-by-step instructions below. Do this when you want to understand how to setup BigBlueButton and make changes to the default configuration.

    If you’ve opted to go thorugh the step-by-step instructions, the first step is to ensure your server is up-to-date.

    1. Update your server

    First, let’s 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 Tomcat can block for a long periods of time (sometimes minutes) before finishing its statup. 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 https://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 https://ubuntu.bigbluebutton.org/xenial-200/ bigbluebutton-xenial main" | sudo tee /etc/apt/sources.list.d/bigbluebutton.list
    

    Next, 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 their required dependencies.

    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 BigBlueButton using the following command:

    $ sudo bbb-conf --restart
    

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

    You should see output similar to the following:

    $ BigBlueButton Server 2.0.0-RC1 (1414)
                        Kernel version: 4.4.0-1060-aws
                          Distribution: Ubuntu 16.04.4 LTS (64-bit)
                                Memory: 7814 MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): rtmp://example.bigbluebutton.com.com
                                  red5: example.bigbluebutton.com
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                             websocket: 52.201.248.115:7443
                        WebRTC enabled: true
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: example.bigbluebutton.com
                                  port: 80, [::]:80, [::]:443
                                  port: 443 ssl
                        bbb-client dir: /var/www/bigbluebutton
    
    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties (bbb-web)
                          bbb-web host: example.bigbluebutton.com
    
    /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp (API demos)
                                   url: example.bigbluebutton.com
    
    /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: example.bigbluebutton.com
                                ffmpeg: 4.0.1-0york0~16.04
    
    ** 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 you are a developer, you can extract the shared secret for making API calls.

    You can install the API demos (next step) to give you an quick front-end to test the features.

    4. Install API demos (optional)

    The API demos are a set of Java Server Pages (JSP) that implement a web-based interface to test the BigBlueButton API.

    To install the API examples, enter the following 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.

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

    If this server is intended for production, you will want to remove the API demos.

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

    $ BigBlueButton Server 2.0.0-RCX (NNNN)
                        Kernel version: 4.4.0-1060-aws
                          Distribution: Ubuntu 16.04.4 LTS (64-bit)
                                Memory: 7814 MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): rtmp://example.bigbluebutton.com.com
                                  red5: example.bigbluebutton.com
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                             websocket: 52.201.248.115:7443
                        WebRTC enabled: true
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: example.bigbluebutton.com
                                  port: 80, [::]:80, [::]:443
                                  port: 443 ssl
                        bbb-client dir: /var/www/bigbluebutton
    
    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties (bbb-web)
                          bbb-web host: example.bigbluebutton.com
    
    /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp (API demos)
                                   url: example.bigbluebutton.com
    
    /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: example.bigbluebutton.com
                                ffmpeg: 4.0.1-0york0~16.04
    
    ** 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 are installed, which enable anyone with access the server to launch a session (see removing API demos).

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

    If you intend to use this server for production, you should

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

    Also, if your BigBlueButton server is behind a firewall, you may need to speciify the value with an external IP address EXTERNAL_IP_ADDRESS:7443 to avoid getting an error 1002 in the client. For more details see Configure BigBlueButton behind a firewall.

    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://bigbluebutton.example.com/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.

    Configure 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;
    }
    

    If you have the HTML5 client installed, you may need to a few more changes. If enableListenOnly is set to true in /usr/share/meteor/bundle/programs/server/assets/app/config/settings-production.json, as in

    # cat /usr/share/meteor/bundle/programs/server/assets/app/config/settings-production.json | grep enableListenOnly
          "enableListenOnly": true
    

    then Kurento is providing a listen only audio stream for users of the HTML5 client (just as red5 provides listen only audio stream for Flash users). In this case, edit /usr/local/bigbluebutton/bbb-webrtc-sfu/config/default.yml change the value to ip to match the external IP address of the server. For example, if the servers external IP address is 203.0.113.1, then edit this file so the value for ip is as follows

    freeswitch:
        ip: '203.0.113.1'
        port: '5066'
    

    You also need to setup Kurento to use a STUN server.

    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
    

    The above will enable users outside the firewall to access your BigBlueButton server. For users themselves who are behind a firewall, you will want to setup a TURN server (next section).

    Setup a TURN server

    BigBlueButton normally requires a wide range of UDP ports to be available for WebRTC communication. In some network restricted sites or development environments, such as those behind NAT or a firewall that restricts outgoing UDP connections, users may be unable to make outgoing UDP connections to your BigBlueButton server.

    The TURN protocol is designed to allow UDP-based communication flows like WebRTC to bypass NAT or firewalls by having the client connect to the TURN server, and then have the TURN server connect to the destination on their behalf.

    In addition, the TURN server implements the STUN protocol as well, used to allow direct UDP connections through certain types of firewalls which otherwise might not work.

    Using a TURN server under your control improves the success of connections to BigBlueButton and also improves user privacy, since they will no longer be sending IP address information to a public STUN server.

    Required Hardware

    The TURN protocol is not CPU or memory intensive. Additionally, since it’s only used during connection setup (for STUN) and as a fallback for users who would otherwise be unable to connect, the bandwidth requirements aren’t particularly high. For a moderate number of BigBlueButton servers, a single small VPS is usually sufficient.

    Having multiple IP addresses may improve the results when using STUN with certain types of firewalls, but is not usually necessary.

    Having the server behind NAT (for example, on Amazon EC2) is OK, but all incoming UDP and TCP connections on any port must be forwarded and not firewalled.

    Required Software

    We recommend using a minimal server installation of Ubuntu 18.04 where possible. (Ubuntu 16.04 is also ok, but includes an older version of coturn.) The coturn software requires port 443 for its exclusive use in our recommended configuration, which means the server cannot have any dashboard software or other web applications running.

    coturn is already available in the Ubuntu packaging repositories for version 16.04 and later, and it can be installed with apt-get:

    sudo apt-get update
    sudo apt-get install coturn
    

    Note: coturn will not automatically start until configuration is applied (see below).

    Required DNS Entry

    You need to setup a fully qualified domain name that resolves to the external IP address of your turn server. You’ll used this domain name to generate a TLS certificate using Let’s Encrypt (next section).

    Generating TLS certificates

    You can use certbot from Let’s Encrypt to easily generate free TLS certificates. To setup certbot enter the following commands on your TURN server (not your BigBlueButton server).

    sudo add-apt-repository ppa:certbot/certbot
    sudo apt-get update
    sudo apt-get install certbot
    

    You can then run a certbot command like the following to generate the certificate, replacing turn.example.com with the domain name of your TURN server:

    sudo certbot certonly --standalone --preferred-challenges http \
        --deploy-hook "systemctl restart coturn" \
        -d turn.example.com
    

    Current versions of the certbot command set up automatic renewal by default. Note that when certbot renews the certificate, it will restart coturn so coturn will start to use the updated certificate files. This will interrupt any ongoing TURN connections. You may wish to change the schedule of certbot renewals or disable automatic renewal if this is a concern.

    Configure coturn

    coturn configuration is stored in the file /etc/turnserver.conf. There are a lot of options available, all documented in comments in that file. We include a sample configuration below with comments indicating the recommended settings, with some notes in locations where customization is required.

    You can repace the contents /etc/turnserver.conf with this file and make two changes:

    • Replace turn.example.com with the hostname of your TURN server, and
    • Replace <random value> to a random value for a shared secret (instructions for generating a new secret are in a comment in the file).
    # Example coturn configuration for BigBlueButton
    
    # These are the two network ports used by the TURN server which the client
    # may connect to. We enable the standard unencrypted port 3478 for STUN,
    # as well as port 443 for TURN over TLS, which can bypass firewalls.
    listening-port=3478
    tls-listening-port=443
    
    # If the server has multiple IP addresses, you may wish to limit which
    # addresses coturn is using. Do that by setting this option (it can be
    # specified multiple times). The default is to listen on all addresses.
    # You do not normally need to set this option.
    #listening-ip=172.17.19.101
    
    # If the server is behind NAT, you need to specify the external IP address.
    # If there is only one external address, specify it like this:
    #external-ip=172.17.19.120
    # If you have multiple external addresses, you have to specify which
    # internal address each corresponds to, like this. The first address is the
    # external ip, and the second address is the corresponding internal IP.
    #external-ip=172.17.19.131/10.0.0.11
    #external-ip=172.17.18.132/10.0.0.12
    
    # Fingerprints in TURN messages are required for WebRTC
    fingerprint
    
    # The long-term credential mechanism is required for WebRTC
    lt-cred-mech
    
    # Configure coturn to use the "TURN REST API" method for validating time-
    # limited credentials. BigBlueButton will generate credentials in this
    # format. Note that the static-auth-secret value specified here must match
    # the configuration in BigBlueButton's turn-stun-servers.xml
    # You can generate a new random value by running the command:
    #   openssl rand -hex 16
    use-auth-secret
    static-auth-secret=<random value>
    
    # If the realm value is unspecified, it defaults to the TURN server hostname.
    # You probably want to configure it to a domain name that you control to
    # improve log output. There is no functional impact.
    realm=example.com
    
    # Configure TLS support.
    # Adjust these paths to match the locations of your certificate files
    cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
    pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem
    # Limit the allowed ciphers to improve security
    # Based on https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
    cipher-list="ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS"
    # Enable longer DH TLS key to improve security
    dh2066
    # All WebRTC-compatible web browsers support TLS 1.2 or later, so disable
    # older protocols
    no-tlsv1
    no-tlsv1_1
    
    # Log to a single filename (rather than new log files each startup). You'll
    # want to install a logrotate configuration (see below)
    log-file=/var/log/coturn.log
    

    Configure Log Rotation

    To rotate the logs for coturn, install the following configuration file to /etc/logrotate.d/coturn

    /var/log/coturn.log
    {
        rotate 30
        daily
        missingok
        notifempty
        delaycompress
        compress
        postrotate
        systemctl kill -sHUP coturn.service
        endscript
    }
    

    Enabling the coturn service

    The ubuntu package for coturn requires that you edit a file to enable startup. Edit the file /etc/default/coturn and ensure the following line is uncommented:

    TURNSERVER_ENABLED=1
    

    You can then start the coturn service by running

    systemctl start coturn
    

    Configure BigBlueButton to use the coturn server

    You must configure bbb-web so that it will provide the list of turn servers to the web browser. Edit the file /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/spring/turn-stun-servers.xml using the contents below and make edits:

    • replace both instances of turn.example.com with the hostname of the TURN server, and
    • replace <random value> with the secret you configured in turnserver.conf.
    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
    
        <bean id="stun0" class="org.bigbluebutton.web.services.turn.StunServer">
            <constructor-arg index="0" value="stun:turn.example.com"/>
        </bean>
    
    
        <bean id="turn0" class="org.bigbluebutton.web.services.turn.TurnServer">
            <constructor-arg index="0" value="<random value>"/>
            <constructor-arg index="1" value="turns:turn.example.com:443?transport=tcp"/>
            <constructor-arg index="2" value="86400"/>
        </bean>
    
        <bean id="stunTurnService"
                class="org.bigbluebutton.web.services.turn.StunTurnService">
            <property name="stunServers">
                <set>
                    <ref bean="stun0"/>
                </set>
            </property>
            <property name="turnServers">
                <set>
                    <ref bean="turn0"/>
                </set>
            </property>
        </bean>
    </beans>
    

    Restart your BigBlueButton server to apply the changes.

    Going forward, when users connect behind a restrictive firewall that prevents outgoing UDP connections, the TURN server will enable BigBlueButton to connect to FreeSWITCH and Kurento via the TURN server through port 443 on their firewall.

    Upgrading from an earlier build

    Upgrading from 1.0 (or earlier)

    If you want to upgrade a BigBlueButton 1.0 (or earlier) server, which ran on Ubuntu 14.04 64-bit, we recommend to starting with a new Ubuntu 16.04 64-bit server, installing BigBlueButton on it, and transferring over existing recordings.

    Upgrading from 1.1 to 2.0

    To upgrade your BigBlueButton server from 1.1 to 2.0, login to the 1.1 server via SSH and edit the file /etc/apt/sources.list.d/bigbluebutton.list. Edit the line to read

    deb https://ubuntu.bigbluebutton.org/xenial-200/ bigbluebutton-xenial main
    

    Notice the repository URL has changed from xenial-110 to xenial-200. Next, you neeed to update ffmpeg to a newer version. Run the command

    sudo add-apt-repository ppa:jonathonf/ffmpeg-4
    

    You need only do the above steps once. To upgrade enter the following commands

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

    This will upgrade BigBlueButton packages from 1.1 to 2.0 and upgrade ffmpeg to 4.0.1.

    Next, to ensure that all the BigBlueButton configuration files are properly updated with the correct hostname/IP address of your server, enter the following commands and substitute <IP_or_hostname> with the IP address or hostname of your BigBlueButton server (use whichever the server had previously been configured for).

    sudo bbb-conf --setip <IP_or_hostname>
    sudo bbb-conf --check
    

    Upgrading to latest build of BigBlueButton 2.0

    Note: If you are looking to upgrade your 1.1 server to 2.0, see Upgrading to 2.0.

    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
    

    If you have installed the HTML5 client, see these further steps for upgrading the configuration files to the latest build of the HTML5 client; otherwise, you can complete the upgrade with the following steps

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

    Common Customizations

    There are a number of common customizations that administrators do to their BigBlueButton server after inital install.

    Remove the API demos

    If you are setting up a production server with custom front-end, you will want to remove the API demos after testing. To remove the API demos, enter the command:

    $ sudo apt-get purge bbb-demo
    

    Extract the shared secret

    All front-ends need two pieces of information from your BigBlueButton server: a hostname and shared secret. Use the command bbb-conf --secret tool to get your BigBlueButton server’s URL and shared secret.

    $ bbb-conf --secret
    
           URL: http://bigbluebutton.example.com/bigbluebutton/
        Secret: 577fd5f05280c10fb475553d200f3322
    
          Link to the API-Mate:
          http://mconf.github.io/api-mate/#server=http://10.0.3.132/bigbluebutton/&sharedSecret=577fd5f05280c10fb475553d200f3322
    

    The link to API-Mate is an excellent tool provided by Mconf Technologies, a company that has made many contributions to the BigBlueButton project over the years. API-Mate lets you interactively create API calls to test your server.

    Assign a hostname

    For any production BigBlueButton server, you need to assign it a hostname. If you have not done so already, you need to purchase a domain name from a domain name service (DNS) provider and, using the provider’s web interface, configure an A record to point 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? The BigBlueButton server comes ready to list to API calls, but doesn’t have a front-end installed by default. You can easily install the API demos to test the server. We’ll cover installing the API demos in the next step.

    However, you don’t need the API demos if you intend 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.

    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.

    Install the HTML5 client

    The BigBlueButton project has been activly developing an HTML5 client for mobile and desktop devices. While the HTML5 client is initially targeting viewers os, it can upload documents, make a user presenter, share screen, and start/stop recording – all the functionalty needed to run a meeting.

    For more information on the HTML5 client, along with links to install steps, see HTML5 client.

    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)"/>
    -->
    

    The default BigBlueButton installation does not come with any music files. You’ll need to upload a music file in WAV format to the server and change a reference in /opt/freeswitch/conf/vars.xml.

    For example, to use the file /opt/freeswitch/share/freeswitch/sounds/en/us/callie/ivr/48000/ivr-to_listen_to_moh.wav as music on hold, edit /opt/freeswitch/conf/vars.xml and change the line

      <X-PRE-PROCESS cmd="set" data="hold_music=local_stream://moh"/>
    

    to

      <X-PRE-PROCESS cmd="set" data="hold_music=/opt/freeswitch/share/freeswitch/sounds/en/us/callie/ivr/48000/ivr-to_listen_to_moh.wav" />
    

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

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

    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.

    Other configuration options

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

    Change processing interval for recordings

    Normally, the BigBlueButton server begins processing the data recorded in a session soon after the session finishes. However, you can change the timing for processing by creating an override for the default bbb-record-core.timer.

    For example, to process recordings between 18:00 to 05:59, enter

    sudo systemctl edit bbb-record-core.timer
    

    which will open a text editor. Copy ad paste in the following contents:

    [Timer]
    # Disable the default timer
    OnUnitInactiveSec=
    
    # Run every minute from 18:00 to 05:59
    OnCalendar=18,19,20,21,22,23,00,01,02,03,04,05:*
    

    and save the file.

    See the man page systemd.time (under CALENDAR EVENTS) for more details about the syntax for OnCalendar=.

    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

    After transfer of recordings (see above), view a sampling of the recordings to ensure they playback correctly (they should).

    If you have transferred over the raw content, you can also reprocess the recordings using the newer scripts to rebuild them with the latest playback format (including any bug fixes made in the latest version). Note: Re-processing can take a long time (around 25% to 50% of the original length of the recordings), and will use a lot of CPU on your new BigBlueButton server while you wait for the recordings to process.

    If you are interested in reprocessing the older recordings, try it first with one or two of the larger recordings. If there is no perceptible difference, you don’t need to reprocess the others.

    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 re-processing of a single recording, you can do

    $ bbb-record --rebuild <recording_id>
    

    where <recording_id> is the the file name of the raw recording in /var/bigbluebutton/recording/raw, such as

    $ bbb-record --rebuild f4ae6fd61e2e95940e2e5a8a246569674c63cb4a-1517234271176
    

    If you want to rebuild all your recordings, enter the command

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

    Migrate recordings from a previous version

    Depending of the previous version there may be some differences in the metadata generated. In order to fix that it will be necessary to execute the corresponding scripts for updating the migrated recordings.

    $ cd /usr/local/bigbluebutton/core/scripts
    

    From version 0.9

    $ sudo ./bbb-0.9-beta-recording-update
    $ sudo ./bbb-0.9-recording-size
    

    From version 1.0

    $ sudo ./bbb-1.1-meeting-tag
    

    If for some reason the scripts have to be run more than once, use the –force modifier.

    $ sudo ./bbb-x.x-script --force
    

    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 layout

    To change the default layout, edit the file /var/www/bigbluebutton/client/conf/config.xml and change the value for defaultLayout in

        <layout showLogButton="true" defaultLayout="bbb.layout.name.defaultlayout"
    

    to the index for the corresponding layout defined in /var/www/bigbluebutton/client/conf/layouts.xml (such as bbb.layout.name.webcamsfocus).

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

    Install client self-check

    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 using the Flash client.

    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
    

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

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

    Tomcat give an error Cannot assign requested address on startup

    If your server has multiple IP addresses, Tomcat might not pick the right address to bind. This could throw an error on installation when tomcat is attempting to install.

    Check /var/log/tomcat7/catalina.out for the following error

    Jan 30, 2018 9:17:37 AM org.apache.catalina.core.StandardServer await
    SEVERE: StandardServer.await: create[localhost:8005]:
    java.net.BindException: Cannot assign requested address (Bind failed)
     at java.net.PlainSocketImpl.socketBind(Native Method)
    

    If you see this, first ensure that there isn’t another copy of tomcat running by doing ps -aef | grep tomcat7. If you do see another copy running, try killing it and then restarting tomcat.

    If you still see the same error in catalina.out, then /etc/tomcat7/server.xml and change

    <Server port="8005" shutdown="SHUTDOWN">
    
    <Server address="0.0.0.0" port="8005" shutdown="SHUTDOWN">
    

    Restart tomcat7 again and it should start normally.

    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.

    WebRTC video not working with Kurento

    Check the value for /proc/sys/net/ipv4/tcp_syncookies that it contains the value 1.

    # cat /proc/sys/net/ipv4/tcp_syncookies
    1
    

    If not, edit /etc/sysctl.conf and set the value for net.ipv4.tcp_syncookies to 1.

    net.ipv4.tcp_syncookies = 1
    

    Save the file and restart.

    Package install failes with sed error

    Some of the BigBlueButton packages use sed scripts to extract contents from configuration files. If the file does not exist at the time of the script’s execution, or the sed script matches multiple entries in a file (such as when a configuration line is commented out), you can see an error such as

    Setting up bbb-client (1:2.0.0-374) ...
    sed: -e expression #1, char 42: unterminated `s' command
    dpkg: error processing package bbb-client (--configure):
     subprocess installed post-installation script returned error exit status 1
    dpkg: dependency problems prevent configuration of bbb-config:
     bbb-config depends on bbb-client; however:
      Package bbb-client is not configured yet.
    
    dpkg: error processing package bbb-config (--configure):
     dependency problems - leaving unconfigured
    Errors were encountered while processing:
     bbb-client
     bbb-config
    E: Sub-process /usr/bin/dpkg returned an error code (1)
    

    In thie above example, the /var/lib/dpkg/info/bbb-client.postinst failed to finish. To debug, edit this file and change the first line to read

    #!/bin/bash -ex
    

    and run

    sudo apt-get install -f
    

    You should now see each command in bbb-conf.postinst as it executes upto the line in which the error occurs. Post this output to https://groups.google.com/forum/#!forum/bigbluebutton-setup for help in resolving the issue.

    Configure BigBluebutton/FreeSWITCH to support IPV6

    The HTML5 client now enables users on mobile devices to connect to a BigBlueButton server. However, on some cellular networks iOS devices only receive an IPV6 address.

    To enable BigBlueButton (FreeSWITCH) to accept incoming web socket connections on IPV6, the BigBlueButton server must have an IPV6 address. You also need to make the following changes to the server.

    First, create the file /etc/nginx/conf.d/bigbluebutton_sip_addr_map.conf with this content:

    map $remote_addr $freeswitch_addr {
        "~:"    [2001:db8::1];
        default    192.0.2.1;
    }
    

    replacing the ip addresses 192.0.2.1 with the system’s external IPV4 addresses, and replace 2001:db8::1 with the system’s external IPV6 address. Next, edit the file /etc/bigbluebutton/nginx/sip.nginx to have the following:

    proxy_pass https://$freeswitch_addr:7443;
    

    Next, ensure all of the following params are present in freeswitch’s sip_profiles/external-ipv6.xml:

    • ws-binding
    • wss-binding
    • rtcp-audio-interval-msec
    • rtcp-video-interval-msec
    • dtmf-type
    • liberal-dtmf
    • enable-3pcc

    If any are missing, copy them from sip_profiles/external.xml, then restart BigBlueButton (sudo bbb-conf --restart).

    FreeSWITCH fails to bind to IPV4

    In rare occasions after shutdown/restart, the FreeSWITCH database can get corrupted. This will cause FreeSWITCH to have problems binding to IPV4 address (you may see error 1006 when users try to connect).

    To check, look in /opt/freeswitch/var/log/freeswitch/freeswitch.log for errors related to loading the database.

    2018-10-25 11:05:11.444727 [ERR] switch_core_db.c:108 SQL ERR [unsupported file format]
    2018-10-25 11:05:11.444737 [ERR] switch_core_db.c:223 SQL ERR [unsupported file format]
    2018-10-25 11:05:11.444759 [NOTICE] sofia.c:5949 Started Profile internal-ipv6 [sofia_reg_internal-ipv6]
    2018-10-25 11:05:11.444767 [CRIT] switch_core_sqldb.c:508 Failure to connect to CORE_DB sofia_reg_external!
    2018-10-25 11:05:11.444772 [CRIT] sofia.c:3049 Cannot Open SQL Database [external]!
    

    If you see these errors, clear the FreeSWITCH database (BigBlueButton doesn’t use the database and FreeSWITCH will recreate it on startup).

    sudo systemctl stop freeswitch
    rm -rf /opt/freeswitch/var/lib/freeswitch/db/*
    sudo systemctl start freeswitch
    

    Older versions

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

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

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