Welcome to the installation guide for BigBlueButton 1.1-beta (referred hereafter as BigBlueButton 1.1). See overview of what is new in this release.

    BigBlueButton is an open source web conferencing system for online learning. BigBlueButton enables instructors to provide remote students a high-quality learning experience.

    To setup BigBlueButton 1.1 we recommend you start with a clean Ubuntu 16.04 64-bit server that is not running other web applications. Doing this will avoid many subtle conflicts, such as with networking and with underlying configuration files, that will cause errors when installing and running BigBlueButton.

    If you are looking to upgrade an existing BigBlueButton server, we recommend starting with a clean Ubuntu 16.04 64-bit server, installing BigBlueButton using the steps below, and then transferring over existing recordings from your older server.

    Installation Video

    If you want to see a walk-through of the installation steps below, we’ve created installation video that demonstrates how to

    • install BigBlueButton 1.1 on an new server,
    • assigning a hostname, and
    • configuring it with SSL certificate from Let’s Encrypt.

    Click the image below to view the video.

    Installation Video Walkthrough

    Before you install

    These instructions will walk through in details of installing BigBlueButton 1.1 on a new server.

    Minimum Server Requirements

    The minimum server requirements for installing BigBlueButton 1.1 are

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

    Other recommendations are

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

    Why do we recommend a bare metal server? BigBlueButton uses FreeSWITCH for processing of incoming audio packets, and FreeSWITCH works best in a non-virtualized environment (see FreeSWITCH recommended configurations).

    Using a virtualized machine (VM) works fine for development and testing. Also, you probably don’t need 500G free for such use (40G would be more than sufficient).

    What about bandwidth for users? For users running the BigBlueButton client we recommend (a minimum of) 1.0 Mbits/sec download speed and 0.5 Mbits/sec upload speed. If the presenter intends to share their desktop, a minimum of 1.0 Mbits/sec upload speed is good.

    In addition to ensuring your server meets the above requirements, there are a few more checks to ensure you have a smooth install procedure.

    Check the server before installation

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

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

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

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

    You need to then logout and log back into your SSH session (this will reload your configuration). Next, run cat /etc/default/locale and 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 setting for LC_ALL before continuing.

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

    $ uname -m
    x86_64
    

    If it doesn’t show x86_64, then you need to re-install the 64-bit version of Ubuntu 16.04.

    Next, check that the version of 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"
    

    Can you install BigBlueButton 1.1 on a different of Ubuntu or Linux? We have designed, developed, installed, and tested BigBlueButton 1.1 on a single distribution of Ubuntu: 16.04 64-bit (Xenial Xerus). That’s what we recommend you use.

    Why the focus on only Ubuntu 16.04? It’s a choice of quality over quantity. We figured long ago it would be better for the BigBlueButton community to have solid installation for a specific version of Linux that works really, really well than to have many installations that don’t work well. We do get occasional request for a CentOS.

    Hostname and SSL certificate

    While you can run BigBlueButton server using just it’s IP address – which is fine for development. However, if you are going to run the server in production, we recommend assigning it a proper hostname, such as bigbluebutton.example.com, as some browser won’t let the use share a webcam or microphone if the web application loads from an IP address.

    There are many domain name registrars that will provide you a hostname, such as GoDadday and Network Solutions.

    You’ll also want to obtain a secure socket layers (SSL) certificate for the hostname so the BigBlueButton server can serve its pages via HTTPS. This will avoid many browser warnings when users are accessing your BigBlueButton server.

    Installing BigBlueButton 1.1-beta

    Here’s a quick checklist:

    1. You have a clean Ubuntu 16.04 64-bit server that meets the minimum specifications.
    2. You have a hostname that you can assign to the server’s IP address.
    3. You have a SSL certificate for the hostname.

    If you are setting up BigBlueButton for development or testing, you can probably skip (2) and (3) for now.

    Also, if you need commercial support for installation or hosting, see http://bigbluebutton.org/support for a list of companies that can help you.

    OK, let’s get started!

    1. Update your server

    First, ensure 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, 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

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

    or

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

    Don’t worry if the 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 sources.list file.

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

    Are you installing BigBlueButton on a virtual server? If so, some of BigBlueButton’s components, such as Tomcat 7, need a source of entropy when starting up. However, in some virtualized environments, the available entropy can run low and cause these components to block for a long period before finishing their startup sequence (See this link for more details if you are curious). To give the virtualized server lots of entropy, install a packaged called haveged (a simple entropy daemon):

    $ sudo apt-get install haveged
    

    Note: You don’t need to run the above command if you are installing BigBlueButton on a bare metal server.

    Now, let’s update your server to the latest packages (and security fixes) for Ubuntu.

    $ 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

    The Ubuntu packages for BigBlueButton are digitally signed. To install them, you need to add the corresponding public key so apt-get can validate the signed packages.

    To do this, enter the following command

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

    Next, so your server knows where to download the BigBlueButton packages, add the BigBlueButton repository to the list of available sources.

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

    Finally, update apt-get so it fetches a new list of available packages.

    $ sudo apt-get update
    

    3. Install BigBlueButton

    We’re now ready to install BigBlueButton.

    $ sudo apt-get install bigbluebutton
    

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

    Install

    Type ‘Y’ and press enter to install.

    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.

    Once the install is finished, restart all the BigBlueButton components.

    $ bbb-conf --restart
    

    Next, run the BigBlueButton configuration utility bbb-conf --check. This utility runs a few dozen checks on your server and tries to find any potential errors in its configuration.

    If everything is good, you should see output similar to the following (of course with a different IP address than 10.0.3.192).

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

    The items under Potential problems may indicate configuration errors or installation errors. Many of these messages will give you recommendations on how to resolve the issue. If you are installing on Amazon EC2, your server will have an internal and external IP address. The BigBlueButton package scripts won’t be able to automatically configure FreeSWITCH (which handles the audio). If you are installing on Amazon EC2, to complete the configuration of FreeSWITCH, see audio not working.

    At this point, your BigBlueButton server is listening to an IP address. If you have a hostname ready, configure its DNS entry (use whatever front end provided by your domain name registrar) to point the hostname to the IP address of the server. Next, you can update all of BigBlueButton’s configuration files to use the hostname with a single command.

    $ bbb-conf --setip <hostname>
    

    For example, if your hostname was bigbluebutton.example.com, you would enter

    $ 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 your server’s default welcome page, you would get an error HTTP Status 404 - /demo/demo1.jsp.

    Why? This page requires the API demos to process the join request. To test your BigBlueButton server, you can install/uninstall the API demos (covered in next step).

    Alternatively, you may already have an existing front-end. For example, if you have a Moodle server, you’ll want to configure it to use your BigBlueButton server through the BigBlueButton Moodle Plugin. This way, Moodle users can launch into virtual classrooms using Moodle.

    Regardless of which front-end you are using, most need only the BigBlueButton server’s hostname and shared secret. You can get both of these using the following bbb-conf command:

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

    Finally, if you are a developer, check out the BigBlueButton API documentation for how to integrate BigBlueButton with your application.

    4. Install API Demos (optional)

    If you want to try out your BigBlueButton server, you can install the API demos using the command

    $ sudo apt-get install bbb-demo
    

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

    Later on, if you wish to remove the API demos, you can enter the command

    $ sudo apt-get purge bbb-demo
    

    5. Install client self-check (optional)

    BigBlueButton provides an end-user self-check application that can help you diagnose networking and configuration issues that may prevent a user from launching or using BigBlueButton.

    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 client self-check page, you can enter the command

    $ sudo apt-get purge bbb-check
    

    6. Restart your server

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

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

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

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

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

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

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

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

    Next, you should configure SSL on your server (see next section).

    Upgrading BigBlueButton 1.1

    The BigBlueButton project will perodically issue updates/bug fixes for a release. If you have already installed BigBlueButton 1.1 and want to upgrade to a newer version, enter the commands

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

    The use of sudo bbb-conf --setip will ensure that all configuration files are updated with the host’s IP address or hostname.

    Configuring SSL on your BigBlueButton

    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

    In order to obtain a valid SSL certificate for your server, you must configure the server to use a domain name that you own or control.

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

    Please run the commands as root.

    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

    In order to serve BigBlueButton over 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, we provide steps to use Let’s Encrypt to obtain a free renewable SSL certificate (exprires after 90 days). See 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;
      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 WebRTC

    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.

    Now the websocket forwarding address in nginx must be updated. 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.3: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

    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 sucessfully
    # enters a name and password, she is redirected here to load the client.
    bigbluebutton.web.serverURL=https://bigbluebutton.example.com

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

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

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

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

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

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

    Edit Demo Files

    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://demo.bigbluebutton.org/bigbluebutton/";
    

    Restart BigBlueButton

    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” checkbox 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 and the server is on the Internet, you can use Let’s Encrypt to obtain a free SSL certificates.

    First, install Let’s Encrypt configuration tool.

    $ sudo apt-get install letsencrypt
    

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

    $ sudo mkdir /etc/nginx/ssl
    $ sudo 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 yourserver.example.com with your own DNS name), to configure the BigBlueButton server with your hostname.

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

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

    $ sudo letsencrypt --webroot -w /var/www/bigbluebutton-default/ -d yourserver.example.com certonly
    
    IMPORTANT NOTES:
     - Congratulations! Your certificate and chain have been saved at
       /etc/letsencrypt/live/yourserver.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/yourserver.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 yourserver.example.com with your hostname).

    server {
      server_name yourserver.example.com;
      listen 80;
      listen [::]:80;
      listen 443 ssl;
      ssl_certificate /etc/letsencrypt/live/yourserver.example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/yourserver.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.

    Troubleshooting Installation

    This section will help you resolve common errors with installation of BigBlueButton.

    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 Coniguring 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 havaged

    $ 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 server has multiple network connections, the install scripts may have used the wrong IP for BigBlueButton’s configuration. Another possibility is you want to access BigBlueButton through a hostname (but not IP).

    To change all of BigBlueButton’s configuration files to use a different IP address or hostname, enter

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

    For more information see bbb-conf options.

    Audio not working

    If you are installing BigBlueButton on EC2 or a hosting provider that has a number of network interfaces, you need to tell FreeSWITCH to listen on your external interface on it’s IP address (shown below as EXTERNAL_IP_ADDRESS). You must use the external IP address where EXTERNAL_IP_ADDRESS is show (not the external hostname).

    Edit /opt/freeswitch/conf/vars.xml

    Remove this line

    <X-PRE-PROCESS cmd="set" data="local_ip_v4=xxx.yyy.zzz.qqq"/>
    

    Change

    <X-PRE-PROCESS cmd="set" data="bind_server_ip=auto"/>
    

    To

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

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

    Edit /opt/freeswitch/conf/sip_profiles/external.xml and change

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

    to

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

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

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

    If you have not configured your server for SSL, edit /etc/bigbluebutton/nginx/sip.nginx to

    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 configured your server for SSL, edit /etc/bigbluebutton/nginx/sip.nginx to

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

    changing EXTERNAL_IP_ADDRESS to your server’s elastic IP address.

    Open the following TCP and UPD ports on the local firewall (if you have one installed) and security groups (if your using EC2):

    • TCP - 80, 443
    • UDP - 16384 to 32768
    • TCP - 5066 (if you do not have SSL enabled)
    • TCP - 7443 (if you do have SSL enabled)

    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
    

    Voice Application failed to register with sip server

    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
    

    If the above does not resolve your problem, post to the output of the commands sudo bbb-conf --check and ifconfig to bigbluebutton-setup and we’ll help you there. `

    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.

    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 service nginx restart
    

    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
    

    Importing recordings from older server

    There are two ways of importing recordings from an old BigBlueButton server to a new one; they are described separately.

    Transfer existing published recordings

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

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

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

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

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

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

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

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

    $ bbb-conf --setip <ip_address_or_hostname>
    

    For example,

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

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

    Re-process raw recordings

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

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

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

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

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

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

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

    And initiate the recording re-processing

    $ bbb-record --rebuildall
    

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

    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 sufficent 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, 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.

    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.