Welcome to the install guide for BigBlueButton.

    This document guides you through installing BigBlueButton 2.2-RC (referred hereafter as simply BigBlueButton). For an overview of the product see the documentation home page.

    BigBlueButton is not your average web application. It’s a fully responsive single page web application that uses the browser’s built-in capabilities to send/receive audio and video. The BigBlueButton server runs a number of back-end processes to handle media, incoming API calls, processing of uploaded slides, and conversion of captured media into recordings.

    Full HTML5 client

    BigBlueButton uses a full HTML5 client for it’s interface. This means the same client runs on desktop, laptop, chromebook, and your mobile devices (iOS 12.2+ and Android 6.0+). We recommend Chrome and FireFox as these browsers provide the best support for webRTC.

    The BigBlueButton client offers

    • 2x faster loading than the previous version
    • High-quality audio, video, and screen sharing (using WebRTC)
    • Shared notes for multi-user editing (using the excellent EtherPad project)
    • Fully accessibile to screen readers
    • Share YouTube videos during the session

    You can try the latest version of the HTML5 client on https://test.bigbluebutton.org/.

    Installation choices

    When installing BigBlueButton you have two choices: bbb-install.sh and step-by-step.

    Regardless of which choice you make, to have a successful installation you need to

    • obtain a dedicated server,
    • ensure the server meets BigBlueButton’s minimum set of requirements,
    • assign a hostname (recommended to set up SSL), and
    • configure the server’s firewall (if needed).

    The two choices are covered below.

    bbb-install.sh

    If you want to set up a BigBlueButton server quickly (or have already setup BigBlueButton servers in the past), then bbb-install.sh will get you up and running with a single command in about 15 minutes.

    Step-by-step

    If you want to understand more of the components of BigBlueButton, you an use the step-by-step instructions in this guilde.

    Getting help

    Regardless of which cooice you make, if you run into any problems, there is an extensive troubleshooting guide section to help you resolve common issues.

    If you encounter problems with installation, we recommend (in order)

    • read through this guide,
    • check out the troubleshooting section,
    • check open issues, and
    • do a quick Google search for your error message.

    There is also a (very) active open source community to help you as well. The BigBlueButton project started in 2007 and it’s installation/setup mailing list has over 2,500+ users.

    If you don’t find a resolution to your issue in these docs or using Google search, then make a post to the bigbluebutton-setup mailing list. Provide a brief description of your issue along with any relevant error messages, and include the following information:

    • What is the version of BigBlueButton you are trying to install?
    • Did you get errors during installation?
      • If so, what were the errors?
    • Did this installation previously work (i.e. were you upgrading to a later release)?
    • Did you make any custom changes to BigBlueButton outside of using bbb-conf?

    By providing the above information, its easier for others to volunteer their time to help you out.

    Before you install

    To set up for a successful install of BigBlueButton, we recommend starting with a ‘clean’ Ubuntu 16.04 64-bit server dedicated for BigBlueButton.

    By ‘clean’ we mean the server does not have any previous web applications installed (such as plesk, webadmin, or apache) that are binding to port 80/443. By ‘dedicated’ we mean that this server won’t be used for anything else besides BigBlueButton (and BigBlueButton-related applications such as Greenlight).

    Minimum server requirements

    The minimum requirements for a BigBlueButton server 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)
    • 4 CPU cores (8 is better)
    • TCP ports 80 and 443 are accessible
    • UDP ports 16384 - 32768 are accessible
    • Port 80 is not in use by another application

    For a server intended for production, we additionally recommend:

    • 500G of free disk space (or more) for recordings
    • 250 Mbits/sec bandwidth (symmetrical) or more
    • Dedicated (bare metal) hardware
    • A hostname (such as bbb.example.com) for setup of a SSL certificate
    • IPV4 and IPV6 address

    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 setting up BigBlueButton for local development on your workstation, you can relax the server requirements a bit because you’ll be the only one using the server. You should be able to run BigBlueButton with

    • 2 CPU cores
    • Installation on a local VM or LXC container
    • IPV4 address only (no hostname)

    However, without configuring SSL on the server, you can’t use web real-time commications (WebRTC) for sharing microphone, webcams, or screen. In other words, all browsers now require the page to be loaded via HTTPS before they let an HTML5 application request access to share media.

    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.

    For minimum requirements for end users, we recommend the latest verison of FireFox or Chrome and the following minimum bandwidth requirements.

    Pre-installation checks

    Got a Ubuntu 16.04 64-bit server ready for installation? Great! But, before jumping into the installation, do a few quick configuration checks to make sure your server meets the minimum requirements.

    Taking a moment to do these checks will significantly reduce the changes you’ll hit a problem during installation.

    First, check that the locale of the server is 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
    

    and then logout and login again to your SSH session – this will reload the locale configuration for your session. 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, do sudo systemctl show-environment and ensure you see LANG=en_US.UTF-8 in the output.

    $ sudo systemctl show-environment
    LANG=en_US.UTF-8
    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    

    If you don’t see this, do sudo systemctl set-environment LANG=en_US.UTF-8 and run the above sudo systemctl show-environment again and confirm you see LANG=en_US.UTF-8 in the output.

    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
    

    Here it shows 31G of memory (it is a server with 32 gigabytes of memory).

    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 kernel 4.x.

    $ uname -r
    4.15.0-38-generic
    

    Next, check that your server has (at least) 4 CPU cores

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

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

    Sometimes we get asked “Why are you only supporting Ubuntu 16.04 64-bit)?”. The answer is based on choosing 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

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

    Do you have a firewall between you and your users? If so, see configuring your firewall.

    Upgrading

    Before you upgrade, if you’ve done any custom changes to BigBlueButton through modifying configuration files, you need to back up those changes first so you can re-apply them after upgrading.

    Upgrading from BigBlueButton 2.2

    if you are upgrading BigBlueButton 2.2, used Let’s Encrypt to setup a SSL/TLS certificate, and you have not done any custom changes to the configuration, then you should be able to run the bbb-install.sh script to upgrade to the latest version of BigBlueButto 2.2.

    If you installed a previous version of BigBlueButton 2.2 using the step-by-step instructions, then you should back any custom changes and then upgrade using the commands below. First upgrade all the packages using dist-upgrade which will install the latest versions of the BigBlueButton 2.2 packages.

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

    Next, use bbb-conf --setip to re-assign your servers IP address or hostname to BigBlueButton’s configuration files.

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

    For example, if you had configured your server with hostname bbb.example.com, you would do

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

    Upgrading from BigBlueButton 2.0

    If you installed a previous version of BigBlueButton 2.0 using the 2.0 installation and then made custom changes, you need to (you guess it!) backup your changes first. After you backup your changes, can then use bbb-install.sh to upgrade or follow the steps below.

    First, you’ll need to uninstall bbb-client

    $ sudo apt-get purge -y bbb-client
    

    and purge the older packages for Kurento with the command

    $ sudo apt-get purge -yq kms-core-6.0 kms-elements-6.0 kurento-media-server-6.0
    $ sudo bbb-conf --restart
    

    You can then choose between the two installation choices for upgrading to BigBlueButton 2.2. After the upgrade is finished, you can re-apply any custom changes.

    Note: If your using bbb-install.sh to upgrade from BigBlueButton 2.0 you don’t need to purge bbb-client and the Kurento packages as the upgrade script will detect your upgrading from BigBlueButton 2.0 and automatically do it for you.

    Installation

    Ready to install? Here’s a quick pre-install checklist:

    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 your firewall to forward the appropriate ports to the BigBlueButton server (and have tested from an external computer that connections are getting through the firewall to your BigBlueButton server).
    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 Let’s Encrypt, which is covered in these docs)

    If you are a developer setting up BigBlueButton for development or testing on a local VM with and intend to use FireFox, you can above skip steps (2), (3), and (4).

    At this point, you are ready to install. Grab a cup of your favorite beverage and let’s begin!

    1. Update your server

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

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

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

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

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

    or this

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

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

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

    If you are a developer installing BigBlueButton on a VM for testing and development, some of BigBlueButton’s components, such as Tomcat, need a source of entropy when starting up. In a VM the available entropy can run low 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.

    There are two applications needed by BigBlueButton: ffmpeg (create recordings) and yq (update YAML files). The default version of ffmpeg in Ubuntu 16.04 is old and yq does not exist in the default repositories. Therefore, before you install BigBlueButton, you need to add the following personal package archives (PPA) to your server to ensure you get the proper versions installed.

    $ sudo add-apt-repository ppa:jonathonf/ffmpeg-4 -y
    $ sudo add-apt-repository ppa:rmescandon/yq -y
    

    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.

    BigBlueButton HTML5 client uses MongoDB, a very efficent database used to synchronize state of the clients. To install MongoDB, do the following

    $ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
    $ echo "deb [ arch=amd64,arm64 ] http://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
    $ sudo apt-get update
    $ sudo apt-get install -y mongodb-org curl
    

    The BigBlueButton HTML5 client requires a nodejs server. To install nodejs, do the following

    curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
    sudo apt-get install -y nodejs
    

    2. Install apt-get key for BigBlueButton repository

    All packages for BigBlueButton are digitally signed with the project’s public key. Before installing BigBlueButton, you need to add the project’s public key to your server’s key chain. To do this, enter the following command:

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

    If you are updating your server from BigBlueButton 2.0 (or earlier version), you need to first remove the bbb-client package.

    $ sudo bbb-conf --stop
    $ sudo apt-get purge -y bbb-client
    

    This is because some files owned by bbb-client have moved to be owned by bbb-web. Deleting the bbb-client package before the upgrade to BigBlueButton 2.2 will allow bbb-web to create these files without conflict from the older version of bbb-client.

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

    $ echo "deb https://ubuntu.bigbluebutton.org/xenial-220/ 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. Back up custom configurations

    If this is a new install you can skip this step.

    If you are upgrading from BigBlueButon2.0, or an earlier release of BigBlueButton 2.2, and have made any custom changes, such as

    • set up your own SSL cerificate in /etc/nginx/sites-available/bigbluebutton,
    • configured FreeSWITCH to accept incoming phone calls,
    • changed the default /var/www/bigbluebutton-default/default.pdf file

    or any other changes outside of using bbb-conf, then you’ll want to backup these changes now before upgrading BigBlueButton. After you upgrade BigBlueButton, you can re-apply the custom configurations to your server.

    4. Install BigBlueButton

    Note: If you are updating from BigBlueButton 2.0 (or earlier), do sudo apt-get purge bbb-client to uninstall bbb-client before installing this newer version.

    We’re now ready to install BigBlueButton. Enter the following two commands

    $ sudo apt-get install bigbluebutton
    $ sudo apt-get install bbb-html5
    

    For each command, when prompted to proceed, type ‘Y’ and press ENTER.

    Note 1: You can ignore any errors “Failure to download extra data files” for the ttf-mscorefonts-installer package. This is a known issue with Ubuntu 16.04.

    Note 2: If the installation exits with an error before finishing, doulbe-check the steps in Before you install. If you find and resolve any configuration errors, you can attempt to finish the installation using the command sudo apt-get install -f.

    Note 3: If you still get errors after sudo apt-get install -f, stop here. The install has not finished and BigBlueButton will not run. See the troubleshooting guide and other options for getting help.

    After the installation finishes, you can make the HTML5 the default client (recommended unless you need the Flash client).

    Finally, to ensure all the packages are up-to-date, do one final dist-upgrade

    $ sudo apt-get dist-upgrade
    

    After the installation finishes, you can make the HTML5 the default client (recommended).

    Next, restart BigBlueButton:

    $ sudo bbb-conf --restart
    

    This will restart all the components of the BigBlueButton server in the proper order. Note: Don’t worry if you initially see # Not running: tomcat7 or grails or Error: Could not connect to the configured hostname/IP address as the startup takes a few moments.

    After the restart finishes, check the setup using bbb-conf --check. When you run this command, you should see output similar to the following:

    $ sudo bbb-conf --check
    
    BigBlueButton Server 2.2.0 (1571)
                        Kernel version: 4.4.0-142-generic
                          Distribution: Ubuntu 16.04.6 LTS (64-bit)
                                Memory: 16432 MB
    
    /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties (bbb-web)
           bigbluebutton.web.serverURL: http://178.128.233.105
                    defaultGuestPolicy: ALWAYS_ACCEPT
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: 178.128.233.105
                                  port: 80, [::]:80
                        bbb-client dir: /var/www/bigbluebutton
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): rtmp://178.128.233.105
                                  red5: 178.128.233.105
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/vars.xml (FreeSWITCH)
                           local_ip_v4: 178.128.233.105
                       external_rtp_ip: stun:stun.freeswitch.org
                       external_sip_ip: stun:stun.freeswitch.org
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                            ext-rtp-ip: $${local_ip_v4}
                            ext-sip-ip: $${local_ip_v4}
                            ws-binding: :5066
                           wss-binding: :7443
    
    /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml (record and playback)
                         playback_host: 178.128.233.105
                     playback_protocol: http
                                ffmpeg: 4.1.1-0york1~16.04
    
    /etc/bigbluebutton/nginx/sip.nginx (sip.nginx)
                            proxy_pass: http://178.128.233.105:5066
    
    
    ** 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.

    You can also use sudo bbb-conf --status to check that all the BigBlueButto processes have started and are running.

    $ sudo bbb-conf --status
    red5 ——————————————————► [✔ - active]
    nginx —————————————————► [✔ - active]
    freeswitch ————————————► [✔ - active]
    redis-server ——————————► [✔ - active]
    bbb-apps-akka —————————► [✔ - active]
    bbb-transcode-akka ————► [✔ - active]
    bbb-fsesl-akka ————————► [✔ - active]
    tomcat7 ———————————————► [✔ - active]
    mongod ————————————————► [✔ - active]
    bbb-html5 —————————————► [✔ - active]
    bbb-webrtc-sfu ————————► [✔ - active]
    kurento-media-server ——► [✔ - active]
    etherpad ——————————————► [✔ - active]
    bbb-web ———————————————► [✔ - active]
    bbb-lti ———————————————► [✔ - active]
    

    At this point, your BigBlueButton server is listening to an IPV4 address. For example, if your server is at IP address 178.128.233.105, you can open http://178.128.233.105/ and see the welcome screen.

    Welcome Screen

    However, you can’t login from this screen unless you install the API demos (you’ll get a 404 error if you try it – the next step shows how to add the API demos).

    If you intend to use this server with another front-end, you don’t need the API demos. You can integrate BigBlueButton with one of the 3rd party integrations by providing the integration the server’s addres and shared secret. You can use bbb-conf to dispaly this information using bbb-conf --secret.

    $ sudo bbb-conf --secret
    
           URL: http://178.128.233.105/bigbluebutton/
        Secret: 330a8b08c3b4c61533e1d0c5ce1ac88f
    
          Link to the API-Mate:
          http://mconf.github.io/api-mate/#server=http://178.128.233.105/bigbluebutton/&sharedSecret=330a8b08c3b4c61533e1d0c5ce1ac88f
    

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

    Join HTML5

    This will join you into the default meeting called “Demo Meeting”. Here’s a screen shot joining using FireFox, opening the Shared Notes panel, drawing on the whiteboard, and sharing a webcam.

    BigBlueButton Interface

    When you are done with the API examples, you can remove them with

    $ sudo apt-get remove bbb-demo
    

    6. Restart your server

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

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

    The bbb-conf --check scans some of the log files for error messages. Again, 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.

    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.

    7. Final steps

    If this server is intended for production, you should

    We provide two publically accessible servers that you can use for testing:

    To learn more about integrating BigBlueButton with your application, check out the BigBlueButton API documentation. To see videos of BigBlueButton HTML5 client, see https://bigbluebutton.org/html5.

    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.

    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:

    $ sudo 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 4096 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:

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

    sudo openssl dhparam -out /etc/nginx/ssl/dhp-4096.pem 4096
    

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

    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 /usr/share/bbb-web/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

    $ sudo 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:

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

    Open /usr/share/meteor/bundle/programs/server/assets/app/config/settings.yml editing and change:

      kurento:
        wsUrl: ws://bbb.example.com/bbb-webrtc-sfu
    

    to

      kurento:
        wsUrl: wss://bbb.example.com/bbb-webrtc-sfu
    

    Also change:

      note:
        enabled: true
        url: http://bbb.example.com/pad
    

    to

      note:
        enabled: true
        url: https://bbb.example.com/pad
    

    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 5, 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:

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

    $ sudo apt-get update
    $ sudo apt-get install software-properties-common
    $ sudo add-apt-repository universe
    $ sudo add-apt-repository ppa:certbot/certbot
    $ sudo apt-get install certbot
    

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

    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.

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

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

    $ sudo certbot --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-4096.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/certbot renew >> /var/log/le-renew.log
    35 2 * * 1 /bin/systemctl reload nginx
    

    These two directives will execute the certbot 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.

    What is not implemented yet

    Almost all the feature sof the Flash have been implemented in the HTML5 client. The remaining features to implement are

    • Ability to close individual webcams (you can turn off all webcams using the settings)
    • Push down a configuration (such as presentation minimized) to viewers
    • Switch slides by selecting a thumbnail

    Customization

    BigBlueButton is a very customizable system, see customizable options.

    Troubleshooting

    If you encounter any problems in the installation, see troubleshooting.