Welcome to the install guide for BigBlueButton.

    This document guides you through installing BigBlueButton 2.2 (referred hereafter as simply BigBlueButton).

    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 its 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 accessible to screen readers
    • Share videos from various providers (YouTube, Twitch, etc.) during the session

    Installation choices

    When installing BigBlueButton you have three choices: bbb-install.sh, Ansible (for large scale deployments) 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 three choices are covered below.


    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 30 minutes.


    If you’re looking to deploy a large-scale installation of BBB using Scalelite then your servers are best managed using tools like Ansible. A few reasons you might go with this setup are:

    • easily customizable: your custom configurations will get replaced every time you upgrade automatically
    • parity across machines: ensure that you deploy the exact same version of BBB on every server
    • eliminate human error in setup: using bbb-install.sh or step-by-step methods are highly prone to human error as you can easily forget if you enabled a setting, chose to do X over Y, etc
    • automate to the fullest: by automating the process, you inherently save time on nasty troubleshooting and hours lost in manual configuration
    • easily scale at large: spin up an identical replica of your BBB server in less than 15 mins with no user input – preconfigured and ready to go

    Choose this method if you are already comfortable with a lot of the technical knowledge behind BigBlueButton, Scalelite and Greenlight/other front-ends. Refer to the following examples to create your installation.

    Note: These examples are not maintained or developed by the official BigBlueButton developers. These are entirely community-sourced, use at your own discretion.

    These first two install BigBlueButton on your server in a consistent fashion. You can specify variables, such as whether to install Greenlight too, what ports to use for TURN, and others. Functionally quite similar to bbb-install.sh but highly automated.

    Large scale deployments must include several other components in addition to the core BigBlueButton packages. These include Scalelite, Greenlight, a database, backups, nginx configurations, and more.


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

    Before you install

    Note: The BigBlueButton project is moving to Ubuntu 18.04. You can install the latest build of BigBlueButton 2.3 (currently in release canddiate 1) following these steps.

    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

    Note: The BigBlueButton project is moving to Ubuntu 18.04. You can install the latest build of BigBlueButton 2.3 (currently in release canddiate 1) following these steps.

    For production, we recommend the following minimum requirements

    • Ubuntu 16.04 64-bit OS running Linux kernel 4.x
    • 16 GB of memory with swap enabled
    • 8 CPU cores, with high single-thread performance
    • 500 GB of free disk space (or more) for recordings, or 50GB if session recording is disabled on the server.
    • TCP ports 80 and 443 are accessible
    • UDP ports 16384 - 32768 are accessible
    • 250 Mbits/sec bandwidth (symmetrical) or more
    • TCP port 80 and 443 are not in use by another web application or reverse proxy
    • A hostname (such as bbb.example.com) for setup of a SSL certificate
    • IPV4 and IPV6 address
    • 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 (also see FreeSWITCH recommended configurations). Additonally, Kurento is used for routing audio-only streams and video streams. Kurento and Freeswitch use different mechanisms to measure the system time/clock. Many vistualized server environments don’t keep those clocks in perfect synchronization and thus cause issues like video & audio being out of sync or broken session recordings as well as other problems related to linux system time.

    That being said, if you want to install BigBlueButton on Amazon EC2, we recommend running BigBlueButton on a c5.2xlarge (or greater CPU) instance. These newer compute instensive instances offer very close to bare-metal performance. On Digital Ocean we recommend the c-8 compute intensive instances. On Hetzner we recommend the AX51 servers or CCX31 instances.

    If you are setting up BigBlueButton for local development on your workstation, you can relax some of the requirements because you’ll be the only one using the server. Starting with the above requirements, you can reduce them as follows

    • 4 CPU cores/8 GB of memory
    • Installation on a local VM or LXC container
    • 50G of disk space
    • IPV4 address only

    You still need to configure SSL on the server; otherwise, you can’t use web real-time communications (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.

    For minimum requirements for end users, we recommend the latest version 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

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

    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_DESCRIPTION="Ubuntu 16.04.x LTS"

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

    $ uname -m

    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

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

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

    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

    You need to have fully qualified domain name (FQDN), such as bigbluebutton.example.com, and secure sockets layer (SSL) certificate (such as one generated using Let’s Encrypt) before BigBlueButton will run.

    For obtaining a domain name, there are many good domain name registrars such as GoDadday and Network Solutions. Free domain names can also be obtained at Freenom.

    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.


    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 BigBlueButton 2.2.

    If you installed a previous version of BigBlueButton 2.2 using the step-by-step instructions, then you should backup any custom changes first (or setup apply-config.sh to automatically apply your updates), 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.

    We’ve changed the PPA for ffmpeg and moved to use the latest version of LibreOffice (6.x). If you have not already done so, enter the following commands

    $ sudo rm -f /etc/apt/sources.list.d/jonathonf-ubuntu-ffmpeg-4-xenial.list
    $ sudo add-apt-repository ppa:bigbluebutton/support
    $ sudo add-apt-repository ppa:libreoffice/ppa

    Next, update the packages with the following commands

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

    After you upgrade (and even if your doing a minor upgrade such as updating 2.2.24 to 2.2.25), you need to do a 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

    If you are upgrading from a very old version of 2.2.x and sudo bbb-conf --check still shows the older version after the above steps, try dpkg --configure -a and then repeat the above steps again.

    Upgrading from BigBlueButton 2.0

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

    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.


    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 start-up. 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 three applications needed by BigBlueButton: ffmpeg (create recordings), yq (update YAML files), and libreoffice (for conversion). 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:bigbluebutton/support -y
    $ sudo add-apt-repository ppa:rmescandon/yq -y
    $ sudo add-apt-repository ppa:libreoffice/ppa

    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 efficient database used to synchronize state of the clients. To install MongoDB, do the following

    $ wget -qO - https://www.mongodb.org/static/pgp/server-3.4.asc | sudo apt-key add -
    $ 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-22/ bigbluebutton-xenial main" | sudo tee /etc/apt/sources.list.d/bigbluebutton.list

    If you are are in Europe, recommend using our European mirrors.

    $ echo "deb https://packages-eu.bigbluebutton.org/xenial-22/ bigbluebutton-xenial main" | sudo tee /etc/apt/sources.list.d/bigbluebutton.list

    An additional package that may not be install but is needed is apt-transport-https to enable obtaining repository information over the https protocol, install it using

    $ sudo apt-get install apt-transport-https

    You may also need to ensure that Ubuntu keys are available. Install them using

    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 6657DBE0CC86BB64

    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 certificate 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)
                    defaultGuestPolicy: ALWAYS_ACCEPT
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name:
                                  port: 80, [::]:80
                        bbb-client dir: /var/www/bigbluebutton
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): rtmp://
                  useWebrtcIfAvailable: true
    /opt/freeswitch/etc/freeswitch/vars.xml (FreeSWITCH)
                       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_protocol: http
                                ffmpeg: 4.1.1-0york1~16.04
    /etc/bigbluebutton/nginx/sip.nginx (sip.nginx)
    ** 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 BigBlueButton 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. However, the BigBlueButton client will not run as it requires you install a SSL certificate.

    After you install a SSL cerificate, you can integrate BigBlueButton with one of the 3rd party integrations by providing the integration the server’s address and shared secret. You can use bbb-conf to display this information using bbb-conf --secret.

    $ sudo bbb-conf --secret
           URL: http://bbb.example.com/bigbluebutton/
        Secret: 330a8b08c3b4c61533e1d0c5ce1ac88f
          Link to the API-Mate:

    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, and you have setup a SSL certificate, you’ll be able to enter your name on the home page and click ‘Join’.
    This will join you into a test meeting.

    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. Next steps

    You need to:

    If this server is intended for production, you should also

    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.


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

    $ ping demo.bigbluebutton.org
    PING demo.bigbluebutton.org ( 56(84) bytes of data.
    64 bytes from 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
    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).

    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 mkdir -p /etc/nginx/ssl
    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_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 specify 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 (here we have EXTERNAL_IP_ADDRESS as, but you would substitute your own external IP):

    location /ws {
      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;
      auth_request /bigbluebutton/connection/checkAuthorization;
      auth_request_set $auth_status $upstream_status;

    Note: As of BigBlueButton 2.2.29 (and later), you can have nginx proxy incoming WSS connections to WS on port 5066 to work around a bug in FreeSWITCH. If you are using 2.2.29 or later, you can run the following BASH script to implement the workaround. Again, here we have EXTERNAL_IP_ADDRESS as, but you would substitute your own external IP.

    EXTERNAL_IP_ADDRESS=  # <-- put in your own external IP address
    yq w -i /usr/share/meteor/bundle/programs/server/assets/app/config/settings.yml public.media.sipjsHackViaWs true
    sed -i 's/https/http/g'  /etc/bigbluebutton/nginx/sip.nginx
    sed -i 's/7443/5066/g'  /etc/bigbluebutton/nginx/sip.nginx
    xmlstarlet edit --inplace --update '//param[@name="ws-binding"]/@value' --value "$EXTERNAL_IP_ADDRESS:5066" /opt/freeswitch/conf/sip_profiles/external.xml
    yq w -i $TARGET freeswitch.sip_ip "$EXTERNAL_IP_ADDRESS"

    If you use bbb-install.sh to install/upgrade BigBlueButton, it will automatically apply the above changes. If you manually upgrade your BigBlueButton server, you can add the above lines to apply-conf.sh to have the above settings applied by bbb-conf when doing the manually upgrade steps.

    If you are manually upgrading from an earlier version of BigBlueButton 2.2, you may get a 1006 error if public.media.sipjsHackViaWs is set to false. Apply the above changes and then restart BigBlueButton.

    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.

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


    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:

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


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

    Also change:

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


        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.

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

    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
     - 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_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, do


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