Welcome to the installation guide for BigBlueButton 1.0. BigBlueButton is an open source web conferencing system for on-line learning. For an overview what new in this release, see overview.

    We recommend you install BigBlueButton 1.0 on a dedicated Ubuntu 14.04 64-bit server that is not running any other web applications. This will avoid subtle conflicts (such as with underlying configuration files) that will cause errors in BigBlueButton installation and running.

    If you already have a BigBlueButton 0.81 server running Ubuntu 10.04, we recommend not trying to upgrade your server. Start with a clean Ubuntu 14.04 64-bit server, install BigBlueButton using the steps below, and then copy over the recordings from the old BigBlueButton server to the new.

    Before you install

    The prerequisites for BigBlueButton 1.0 server are

    • Ubuntu 14.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, 1935, 9123 are accessible
    • UDP ports 16384 - 32768 are accessible
    • Port 80 is not in use by another application
    • 500G of free disk space (or more) for recordings
    • 100 Mbits/sec bandwidth (symmetrical)
    • Dedicated (bare metal) hardware (not virtualization)

    If you intend to setup BigBlueButton for development, then installation in a virtualized environment works well. For development, you probably don’t need a VM with 500G of free disk space; 50G would be sufficient. However, if you intend to run BigBlueButton in production, we recommend installation on a dedicated (bare metal) server. BigBlueButton uses FreeSWITCH for processing the incoming real-time packets for audio, and FreeSWITCH works best in a non-virtualized environment (see FreeSWITCH recommended configurations).

    For users we recommend (a minimum of) 1.0 Mbits/sec download speed and 0.5 Mbits/sec upload speed.

    In addition to ensuring your server meets the above requirements, there are a few more checks. First, the locale of the server must be en_US.UTF-8. To verify , enter the following command

    $ 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
    

    and logout and log back into your SSH session (this will reload your configuration). Run cat /etc/default/locale again 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.

    Check that your server is running 64-bit.

    $ uname -m
    x86_64
    

    Check your version of Ubuntu is Ubuntu 14.04.

    $ cat /etc/lsb-release
    DISTRIB_ID=Ubuntu
    DISTRIB_RELEASE=14.04
    DISTRIB_CODENAME=trusty
    DISTRIB_DESCRIPTION="Ubuntu 14.04.X LTS"
    

    We have designed, developed, installed, and tested BigBlueButton 1.0 on Ubuntu 14.04 64-bit (Trusty Tahr). In other words, we have neither installed nor tested BigBlueButton on a different release of Ubuntu (and it will likely not work).

    Installing BigBlueButton 1.0

    If you have already installed an earlier build of 0.9/1.0 then see upgrading BigBlueButton 0.9

    A few words about the installation steps below. You must completely finish each step before proceeding to the next. If you encounter an error at any step, STOP and double-check you’ve entered the proper commands, and don’t continue onto the next step as you’ll only compound the errors. If you can’t resolve the error (use Google to search for the error messages), then post a description of the error to the bigbluebutton setup mailing list and the community will help.

    Commercial support is also available.

    1. Update your server

    Login to your server via SSH. You need to have an account that can execute commands as root (via sudo). First, ensure that you have trusty multiverse in your sources.list. Do the following.

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

    and you should see an uncommented line for the multiverse repository, which may look like

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

    or

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

    Don’t worry if your URL is different, what’s important is you see an uncommented link that contains multiverse. If you don’t, then execute the following line to add the multiverse repository to your sources.list file.

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

    Before proceeding further, do a dist-upgrade to ensure all the current packages on your server are up-to-date.

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

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

    If you are installing BigBlueButton on EC2 (good for testing, but for production we recommend using a physical server for better performance), Amazon EC2 provides an external and internal IP address. After you install BigBlueButton, complete the steps outlined here.

    2. Install PPA for LibreOffice 4.4 and libssl

    Ubuntu 14.04 installs LibreOffice 4.2.x by default, but we want to use LibreOffice 4.4 for improved stability on conversion of Microsoft Office documents to PDF.

    To add the repository for LibreOffice 4.4, enter the following commands:

    $ sudo apt-get install software-properties-common
    $ sudo add-apt-repository ppa:libreoffice/libreoffice-4-4
    

    Also, Chrome 52 (currently in beta) will rquire ECDSA keys in the audio connection between the browser and FreeSWITCH server. In order for FreeSWITCH to support ECDSA key (and let the user connect with WebRTC audio on Chrome 52+), you need to add the follwing PPA

    $ sudo add-apt-repository -y ppa:ondrej/php
    

    3. Install key for BigBlueButton

    You need to give your server access to the BigBlueButton package repository. First, add the BigBlueButton key

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

    Next, add the BigBlueButton repository URL.

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

    Finally, update the package list.

    $ sudo apt-get update
    

    4. Install ffmpeg

    BigBlueButton 1.0 uses ffmpeg to create components of the playback files (the audio, video, and desktop sharing components).

    To install ffmpeg, create a file called install-ffmpeg.sh and copy-and-paste in the following script.

    sudo apt-get install build-essential git-core checkinstall yasm texi2html libvorbis-dev libx11-dev libvpx-dev libxfixes-dev zlib1g-dev pkg-config netcat libncurses5-dev
    
    FFMPEG_VERSION=2.3.3
    
    cd /usr/local/src
    if [ ! -d "/usr/local/src/ffmpeg-${FFMPEG_VERSION}" ]; then
      sudo wget "http://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.bz2"
      sudo tar -xjf "ffmpeg-${FFMPEG_VERSION}.tar.bz2"
    fi
    
    cd "ffmpeg-${FFMPEG_VERSION}"
    sudo ./configure --enable-version3 --enable-postproc --enable-libvorbis --enable-libvpx
    sudo make
    sudo checkinstall --pkgname=ffmpeg --pkgversion="5:${FFMPEG_VERSION}" --backup=no --deldoc=yes --default
    

    Next, make the script executable and run it.

    $ chmod +x install-ffmpeg.sh
    $ ./install-ffmpeg.sh
    

    After the script finishes, check that ffmpeg is installed by typing the command ffmpeg -version. You should see the following

    $ ffmpeg -version
    ffmpeg version 2.3.3 Copyright (c) 2000-2014 the FFmpeg developers
      built on Aug 18 2014 17:35:05 with gcc 4.8 (Ubuntu 4.8.2-19ubuntu1)
      configuration: --enable-version3 --enable-postproc --enable-libvorbis --enable-libvpx
      libavutil      52. 92.100 / 52. 92.100
      libavcodec     55. 69.100 / 55. 69.100
      libavformat    55. 48.100 / 55. 48.100
      libavdevice    55. 13.102 / 55. 13.102
      libavfilter     4. 11.100 /  4. 11.100
      libswscale      2.  6.100 /  2.  6.100
      libswresample   0. 19.100 /  0. 19.100
    

    5. Install BigBlueButton

    We’re now ready to install BigBlueButton 1.0 Type

    $ sudo apt-get install bigbluebutton
    

    This single command is where all the magic happens. This command installs all of BigBlueButton’s components with their dependencies.

    Install

    Type ‘Y’ and press enter to install. If you get an error message

    ...... Error: FreeSWITCH didn't start 
    

    you can ignore it as you’ll do a clean restart of all the BigBlueButton components in step 9.

    ImageMagick security issues

    The version of ImageMagick included with Ubuntu 14.04 is vulnerable to CVE-2016-3714, which can result in remote code execution. To mitigate the issue, please edit the file /etc/ImageMagick/policy.xml and ensure that it has the following contents:

    <policymap>
      <policy domain="coder" rights="none" pattern="EPHEMERAL" />
      <policy domain="coder" rights="none" pattern="URL" />
      <policy domain="coder" rights="none" pattern="HTTPS" />
      <policy domain="coder" rights="none" pattern="MVG" />
      <policy domain="coder" rights="none" pattern="MSL" />
      <policy domain="coder" rights="none" pattern="TEXT" />
      <policy domain="coder" rights="none" pattern="SHOW" />
      <policy domain="coder" rights="none" pattern="WIN" />
      <policy domain="coder" rights="none" pattern="PLT" />
    </policymap>
    

    Run convert -list policy to confirm that the security policies have been applied.

    Some additional policies to limit resource consumption may also be useful, see ImageMagick Policy Configuration for details.

    6. Install API Demos

    This step is optional.

    If you want to interactively test your BigBlueButton server (as opposed to using an 3rd party integration), you can install a set of API demos.

    $ sudo apt-get install bbb-demo
    

    You’ll need the bbb-demo package installed if you want to join the Demo Meeting from your BigBlueButton server’s welcome page. This is the same welcome page you see at demo server.

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

    $ sudo apt-get purge bbb-demo
    

    7. Install Client Self-Check

    This step is optional

    BigBlueButton has a self-check utility that can help diagnose networking and configuration issues that may prevent a user from launching BigBlueButton. To install the client self-check page:

    $ sudo apt-get install bbb-check
    

    This is the same welcome page you see at client self-check.

    Later on, if you wish to remove the client self-check page, you can enter the command

    $ sudo apt-get purge bbb-check
    

    8. Enable WebRTC audio

    To enable WebRTC audio (you want to do this), do the following

    $ sudo bbb-conf --enablewebrtc
    

    9. Do a Clean Restart

    To ensure BigBlueButton has started cleanly, enter the following commands:

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

    The --clean option will clear out all the log files for BigBlueButton. The --check option will grep through the log files looking for errors.

    The output from sudo bbb-conf --check will display your current settings and, after the text, “ Potential problems described below “, print any potential configuration or startup problems it has detected.

    Here is a sample output from a new install on a server with hostname demo.bigbluebutton.org.

    $ sudo bbb-conf --check
    
    BigBlueButton Server 1.0.N (NNNN)
                        Kernel version: 3.13.0-85-generic
                          Distribution: Ubuntu 14.04.4 LTS (64-bit)
                                Memory: 7698 MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): demo.bigbluebutton.org
                                  Red5: demo.bigbluebutton.org
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/conf/sip_profiles/external.xml (FreeSWITCH)
                        websocket port: 5066
                        WebRTC enabled: true
    
    /etc/nginx/sites-available/bigbluebutton (nginx)
                           server name: demo.bigbluebutton.org
                                  port: 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
    
    /var/www/bigbluebutton/check/conf/config.xml (client check)
                          client check: demo.bigbluebutton.org
    
    /usr/share/red5/webapps/bigbluebutton/WEB-INF/red5-web.xml (red5)
                      voice conference: FreeSWITCH
                         capture video: true
                       capture desktop: 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
    

    The command sudo bbb-conf --check will also point out potential problems that may be actual problems or warnings. Here, it warns you you currently have the API demos installed, which would enable anyone with access to the server to launch sessions.

    At this point, you could try out your server by opening http://demo.bigbluebutton.org with your web browser (FireFox or Chrome recommended as they support WebRTC audio). There is, in fact, a demo server running at http://demo.bigbluebutton.org if you want to try out BigBlueButton.

    If BigBlueButton didn’t install or run, see troubleshooting installation.

    Upgrading BigBlueButton 0.9/1.0

    If already have a BigBlueButton 0.81 server, these instructions will not upgrade your server. You need to install on a clean installation of 1.0 on Ubuntu 14.04 64-bit and follow the steps previous in this document.

    To upgrade your BigBlueButton 0.9 server, first setup BigBlueButton repository URL as instructed in Step 3.. Next, add the package repository for LibreOffice 4.4 (if you’ve not already done this). To check if you have libreoffice 4.3, enter the command dpkg -l | grep libreoffice and you should see a version 4.4.X of libreoffice.

    $ dpkg -l | grep libreoffice
    
    ii  libreoffice  1:4.3.6~rc2-0ubuntu1~trusty1  amd64  office productivity suite (metapackage)
    ...
    

    If you see

    ii  libreoffice  1:4.2.7-0ubuntu2   amd64        office productivity suite (metapackage)
    ...
    
    

    then enter the following commands to upgrade to LibreOffice 4.4 (you need only do these commands once).

    $ sudo apt-get install software-properties-common
    $ sudo add-apt-repository ppa:libreoffice/libreoffice-4-4
    

    Next,before you upgrade your BigBlueButton 1.0 server (or upgrade 0.9 to 1.0), you need to ensure you have libssl1.0.2 installed to enable FreeSWITCH to support ECDSA keys (see more information). To check, do the following command

    $ dpkg -l | grep libssl
    ii  libssl-dev:amd64   1.0.1f-1ubuntu2.19  amd64  Secure Sockets Layer toolkit - development files
    ii  libssl-doc         1.0.1f-1ubuntu2.19  all    Secure Sockets Layer toolkit - development documentation
    ii  libssl1.0.0:amd64  1.0.1f-1ubuntu2.19  amd64  Secure Sockets Layer toolkit - shared libraries
    

    If you only see libssl1.0.0, then do the following

    $ sudo add-apt-repository -y ppa:ondrej/php
    $ sudo apt-get update
    $ sudo apt-get install libssl1.0.2
    

    After the install you should see the libssl1.0.2 package.

    $ dpkg -l | grep libssl
    ii  libssl-dev:amd64   1.0.1f-1ubuntu2.19  amd64  Secure Sockets Layer toolkit - development files
    ii  libssl-doc         1.0.1f-1ubuntu2.19  all    Secure Sockets Layer toolkit - development documentation
    ii  libssl1.0.0:amd64  1.0.1f-1ubuntu2.19  amd64  Secure Sockets Layer toolkit - shared libraries
    ii  libssl1.0.2:amd64  1.0.2h-1+deb.sury.org~trusty+1  amd64   Secure Sockets Layer toolkit - shared libraries
    

    Your now ready to upgrade. To upgrade BigBlueButton 0.9/1.0, do the following:

    $ sudo apt-get update
    $ sudo apt-get dist-upgrade
    
    $ sudo bbb-conf --enablewebrtc
    $ sudo bbb-conf --clean
    $ sudo bbb-conf --check
    

    Respond with ‘Y’, if you get prompted to update any configuration file during the upgrade

    Configuring HTTPS on BigBlueButton

    You’ll want to add HTTPS support to your BigBlueButton server for increased security. 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.

    Configure nginx to use HTTPS

    Depending on your 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 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 & WebRTC

    Edit the file /opt/freeswitch/conf/sip_profiles/external.xml and look for a line containing “ws-binding”. Add a new line below it, as indicated:

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

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

    In addition, the webrtc code in the client must be updated to use the secure websockets connection. Edit the file /var/www/bigbluebutton/client/lib/bbb_webrtc_bridge_sip.js and change the line that selects the ‘ws’ protocol to use ‘wss’ instead:

    function createUAWithStuns(username, server, callback, stunsConfig, makeCallFunc) {
        console.log("Creating new user agent");
        /* VERY IMPORTANT * - You must escape the username because spaces will cause the connection to fail
         * - We are connecting to the websocket through an nginx redirect instead of directly to 5066 */
        var configuration = {
            uri: 'sip:' + encodeURIComponent(username) + '@' + server,
            wsServers: 'wss://' + server + '/ws',
            displayName: username,
            register: false,
            traceSip: true,
            autostart: false,
            userAgentString: "BigBlueButton",
            stunServers: stunsConfig['stunServers'],
            turnServers: stunsConfig['turnServers']
         };
    
         [...]

    Configure BigBlueButton to load session via HTTPS

    Edit the file /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

    You must also update the file /var/www/bigbluebutton/client/conf/config.xml to tell the client to load components via https. Since this is tedious to do by hand, you can use the following command to apply the change:

    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

    Edit /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp to 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.

    Troubleshooting Installation

    The following will help you resolve common errors with installation.

    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

    At the time of writing, the current release is Chrome 45. As of Chrome 47 (coming soon), Chrome will require that any access to the user’s micrphone for WebRTC be restricted to sites that are served via HTTPS. Users using Chrome Canary will also have this requirement.

    If the user attempts to share their microphone, 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 trusty main restricted universe multiverse
    deb http://archive.ubuntu.com/ubuntu trusty-updates main restricted universe multiverse
    deb http://security.ubuntu.com/ubuntu trusty-security main restricted universe multiverse
    
    

    then do

    $ sudo apt-get update
    

    and try installing BigBlueButton again from the beginning.

    Some packages could not be installed error (libpython3.4)

    Some installations of Ubuntu 14.04 might have broken python3.4 packages installed. To check if this issue affects you, run the following command:

    sudo apt-get install -s libpython3.4
    

    If you get output that looks similar to the following - in particular, if it mentions the python version “3.4.3-1ubuntu1~14.04.1”, then you are hitting this issue:

    libpython3.4 : Depends: libpython3.4-stdlib (= 3.4.0-2ubuntu1.1) but 3.4.3-1ubuntu1~14.04.1 is to be installed 
    

    To fix this problem, run the following commands:

    sudo dpkg -r --force-all libpython3.4-stdlib python3.4-minimal libpython3.4-minimal libpython3.4 python3.4
    sudo apt-get -f install
    

    If those commands complete, you can go back to the installation instructions and try the package that had failed again.

    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
    

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

    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 - 5066
    • UDP - 16384 to 32768
    • TCP - 7443 (if you have HTTPS 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 it’s 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
    

    Reprocess Recordings from 0.81

    With the update from BigBlueButton 0.81 to 0.9, we do not support upgrading a server in place. Instead, we recommend installing a fresh copy of Ubuntu 14.04 for BigBlueButton 0.9.

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

    Re-process raw recordings from an old server

    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@bbb-0-81-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.

    Transfer existing published recordings from an 0.81 server

    If you want to do the minimum amount of work to quickly make your existing recordings on a 0.81 server available on a BigBlueButton 0.9 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@bbb-0-81-server:/var/bigbluebutton/published/ /var/bigbluebutton/published/
    rsync -rP root@bbb-0-81-server:/var/bigbluebutton/unpublished/ /var/bigbluebutton/unpublished/
    rsync -rP root@bbb-0-81-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.

    Finally, if you are transferring recordings from a BigBlueButton 0.80 server, they may have been done in an older recording format called “slides”. In order to correctly play back these recordings on a new BigBlueButton server, you will have to install an additional package:

    apt-get install bbb-playback-slides
    

    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.

    Installing previous versions

    We recommend installing the latest version of BigBlueButton. However, if you wish to install the previous version, see the following links: