Install

How to install this package

Install Big Blue Button

My most reliable configuration uses the bbb-install script from the bigbluebutton/bbb-install repository on an Amazon EC2 instance running Ubuntu 16. Start an c5.2xlarge instance based on ami-05e16100b6f337dda (standard Ubuntu 16), at least 16 GB disk space (12 GB is required for bare-bones installation), a fairly open security group, arrange for a DNS name to point to the instance (I control freesoft.org and use Google dynamic DNS; the ddclient program runs on my instance to register the IP address with Google), then download and run bbb-install, something like this:

sudo ./bbb-install.sh -v xenial-22 -s collaborate.freesoft.org -g -e [email protected]

or this, if you've already got SSL keys and certificates:

sudo ./bbb-install.sh -v xenial-22 -s collaborate.freesoft.org -g -d

SSL configuration is required for proper operation of Big Blue Button.
Configure authentication into Big Blue Button

There are many ways to do this. Installing Greenlight (the -g switch on the bbb-install.sh call above) is probably the simplest. Check the Greenlight documentation for more information about what to do next (like adding users). The default Greenlight configuration allows anybody to sign up as a user, but moderators need to be added from the command line.

Installing Greenlight also installs a Postgres server (both in docker containers), which is handy because we need Postgres to manage our user lookup table. In fact, the database name greenlight_production is (currently) hard-wired in the package.
Clone the BrentBaccala/bigbluebutton repository (not this one)
Install and activate the modified HTML 5 client (needed to get the remote desktop function)
1. In the repository clone's bigbluebutton-html5 directory, run npm install npm-force-resolutions, then npm install
  
  This downloads and installs the various node.js dependencies.
2. We also need meteor npm install --save bowser at the moment
3. Install Meteor: curl https://install.meteor.com/ | sh
4. Select Meteor 1.8: meteor update --allow-superuser --release 1.8
5. Update the Kurento URL in the settings file:
  
  WSURL=`yq r /usr/share/meteor/bundle/programs/server/assets/app/config/settings.yml public.kurento.wsUrl`
  
  sed -i.bak "s|\bHOST\b|$WSURL|" private/config/settings.yml
6. Install Meteor dependencies: meteor npm install
7. Shut down the standard bbb-html5 service
  
  sudo systemctl stop bbb-html5
  
  sudo systemctl disable bbb-html5 (prevents it from starting again on boot)
8. In the clone's bigbluebutton-html5 directory, run npm start
  
  You should now have a working Big Blue Button installation with a new menu option to "share remote desktop".
  
  To keep npm start running, I either run it in a screen session, or install pm2 and run it like this:
  
  pm2 start npm -- start
  
  pm2 can be made persistent pretty easily (run pm2 startup for instructions)
Install and activate the modified Scala server (needed to get the signed JSON Web Tokens used to authenticate the remote desktops)
1. Follow the Big Blue Button installation instructions to install the Scala build tools, something like this:
```
sudo apt-get install git-core ant ant-contrib openjdk-8-jdk-headless
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
curl -s "https://get.sdkman.io" | bash
source "/home/baccala/.sdkman/bin/sdkman-init.sh"
sdk install gradle 5.5.1
sdk install grails 3.3.9
sdk install sbt 1.2.8
sdk install maven 3.5.0
```
2. If you're running Big Blue Button 2.3 on Ubuntu 18, make sure you select Java 8:
  
  sudo update-java-alternatives --set /usr/lib/jvm/java-1.8.0-openjdk-amd64
3. Build bbb-common-message:
```
cd bbb-common-message
./deploy.sh
```
4. In the akka-bbb-apps directory, ensure that the development Scala server gets the same API key as the production server:
  
  cp /usr/share/bbb-apps-akka/conf/application.conf src/universal/conf/application.conf
5. Build and run the modified Scala server. From akka-bbb-apps directory, ./run.sh
Now clone this repository, and from its directory...
Build the vnc_collaborate module: ./setup.py build

You might be missing some packages to make this work:
```
sudo apt install python3-pip
pip3 install setuptools
./setup.py build
```
Install the vnc_collaborate module: sudo -H pip3 install .

It's installed globally so that both the student and teacher accounts have access to it.
You also need to install the websockify module, but it's not installed automatically because it has a dependency problem on Ubuntu 16. Run this to install it:

sudo -H pip3 install --no-deps websockify
You need to install one or the other of psycopg2 or psycopg2-binary; same syntax, i.e:

sudo -H pip3 install psycopg2-binary
You need to install an apt package to get the X11 Tk library:

sudo apt install python3-tk
Check that vnc_collaborate installed correctly: python3 -m vnc_collaborate should run with no output and no error
Install packages needed to run VNC desktops: sudo apt install fvwm tightvncserver ssvnc socat xdotool

Only these packages are strictly required (and tigervncserver should be used instead of tightvncserver), but some other packages are useful:
1. A terminal; sudo apt install gnome-terminal
2. A web browser; sudo apt install firefox
3. A whiteboard; sudo apt install xournal
4. The DBUS server: sudo apt install dbus-x11
5. anything else you'd like to run on your desktops
Put the following one-line config in /etc/skel/.fvwm/config:

PipeRead 'python3 -m vnc_collaborate print fvwm_config'

The FVWM config is shipped with the Python package, and this pulls in the config without having to hard-wire the location where the package is installed.

The scripts detect at runtime whether the user is in group bigbluebutton and selects either teacher or student configuration automatically.
Create a UNIX account for the teacher using something like:

sudo adduser --force-badname BrentBaccala

There's no naming convention that has to be followed here, the account doesn't have to be given a password (you'll be prompted for a VNC password in a moment), and I needed --force-badname only because the name I choose didn't pass Ubuntu's standard account name regular expression test.

If just hit return six times when prompted for a password, it will create the account with no password.

Put the teacher account in the bigbluebutton group:

adduser BrentBaccala bigbluebutton
Create UNIX user accounts for the students. No passwords need be set; no special group is required.
Configure a Postgres table to map the Big Blue Button users to UNIX useres.

The user 'vnc' with password 'vnc' and database 'greenlight_production' is currently hard-wired into the package for Postgres authentication, so it's best to install Greenlight and create this role using a tool like psql or pgadmin3 (authenticate using the credentials in the greenlight/.env file):

CREATE ROLE vnc LOGIN PASSWORD 'vnc';

Create the table (or view) using the following SQL command:

CREATE TABLE VNCusers(VNCuser text NOT NULL, UNIXuser text, rfbport integer, PRIMARY KEY (VNCuser));

The only permission 'vnc' needs is to read this table:

GRANT SELECT ON VNCusers to vnc;

The grant isn't too broad, since it only allows read-only access to this one table, and the default Greenlight configuration (the port mapping in its docker-compose.yml file) only allows connections from localhost.

Use psql or pgadmin3 to add entries into the VNCusers table mapping the Big Blue Button names to the UNIX usernames.

psql requires SQL commands something like:

INSERT INTO VNCusers (VNCuser, UNIXuser) VALUES ('Brent Baccala (DCPS)', 'baccala');

If they're setup right, run a query and you should see something like this:

$ psql -h localhost -U postgres -d greenlight_production -c "select * from vncusers"
         vncuser        |   unixuser   
 -----------------------+--------------
  Baccala, Brent (DCPS) | baccala
  Charlie Clown         | CharlieClown
  Jimmy Brown           | JimmyBrown
  Freddy Frown          | FreddyFrown
  Nancy Noun            | NancyNoun
 (5 rows)

Start websockify to relay WebSock connections to the VNC server, something like this:

python3 -m vnc_collaborate websockify -D --ssl-only --cert $HOME/ssl/fullchain1.pem --key $HOME/ssl/privkey1.pem 6101 localhost:0

I often run this command in a screen session without the -D option if I want to monitor its operation.

The host and port specified as the last option to the websockify command now become a default VNC session that users will connect to if the username lookup fails. Using port 0 gives a blank screen to an unconfigured user.

Notice that special arrangements have been made (I copied the SSL keys and certs from /etc/letsencrypt/archive into my home directory) to enable encrypted connections. Reading these SSL files is the only special permission that websockify needs.

Also note that we're using a special websockify built-in to the vnc_collaborate module. This custom websockify will relay VNC connections to different VNC servers based on a UNIX user name that can be (optionally) provided in the URL (see below).

If the SQL table contains a mapping from a Big Blue Button user to a UNIX user, but no running VNC server is found for that user, the websockify script will attempt to start one by running sudo -u USER -i vncserver.

If this feature is desired, then websockify must be run with permission to execute this sudo operation. The simplest way to do this is to run websockify from an account (ubuntu on an AWS EC2 instance) that can execute any operation as any user, but this may present too much of a security risk.

If this feature is not enabled (i.e, websockify is unable to execute the sudo), then the student VNC servers must be started in some other way. The scripts also expect the VNC desktops to be available via UNIX domain sockets in /run/vnc; this is what socat is used for (see websockify.py)

If you want to connect via port 443 instead of port 6101 (required by some firewalls), put the following config fragment in /etc/bigbluebutton/nginx/vnc.nginx:

location /vnc/ {
        proxy_pass https://localhost:6101/;

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

...and restart nginx (sudo systemctl restart nginx)

At this point, all the desktops configured in SQL should be working.

From a Big Blue Button session, "share remote desktop" and use the URL wss://HOST/vnc/{jwt}

If you didn't setup the proxy in the previous step, use wss://HOST:PORT/{jwt}

If you get handler exception: [Errno 13] Permission denied from the websockify (you'd have to run it without the -D option to see any messages from it at all), double-check the permissions on your SSL files.
Inside the teacher (and the student) desktops, you probably want to run gnome-settings-daemon in background, to permit control over the display fonts.

You might need to install the program: sudo apt install gnome-settings-daemon.

I then like to run gsettings set org.gnome.desktop.interface font-name 'Monospace 16' to set the fonts on the menus. The title bar fonts are set in the FVWM config file. The font used by gnome-terminal can be set either from its preferences dialog or by running `gsettings set org.gnome.desktop.interface monospace-font-name 'Monospace 16'.

You can also install and run gnome-tweak-tool, which is a GUI interface to these settings.
The VNC servers have no VNC authenication, so block all attempts to connect directly to the VNC port range except on the loopback interface:

sudo iptables -A INPUT -p tcp -m tcp --dport 5900:5999 \! -i lo -j DROP

Also block local access to the VNC desktops, except root access, which is required:

sudo iptables -A OUTPUT -p tcp -m tcp --dport 5900:5999 -m owner ! --uid-owner 0 -j DROP

Neither of these will be needed once we switch to a newer version of Xtigervnc, which can listen directly on UNIX domain sockets (without using TCP at all) and doesn't require socat to relay UNIX connections to TCP.
Drop me a line at [email protected].

In particular, I'm changing the design of the scripts fairly frequently right now (October 2020), so let me know so I can let you know when these instructions change.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Install

Clone this wiki locally