Install

How to install this package

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

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

3. Clone the BrentBaccala/bigbluebutton repository (not this one)

4. Install and activate the modified HTML 5 client (needed to get the remote desktop function)

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

6. We also need meteor npm install --save bowser at the moment

7. Install Meteor: curl https://install.meteor.com/ | sh

8. Select Meteor 1.8: meteor update --allow-superuser --release 1.8

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

10. Install Meteor dependencies: meteor npm install

11. Shut down the standard bbb-html5 service

    sudo systemctl stop bbb-html5

    sudo systemctl disable bbb-html5 (prevents it from starting again on boot)

12. 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)

13. 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, bbb-common-message, and akka-bbb-apps

    2. Stop the Scala server

       sudo systemctl stop bbb-apps-akka

       sudo systemctl disable bbb-apps-akka (prevents it from starting again on boobt)

    3. Run the modified Scala server. From akka-bbb-apps directory, ./run.sh

14. Now clone this repository, and from its directory...

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

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

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

18. You need to install one or the other of psycopg2 or psycopg2-binary; same syntax, i.e:

    sudo -H pip3 install psycopg2-binary

19. You need to install an apt package to get the X11 Tk library:

    sudo apt install python3-tk

20. Check that vnc_collaborate installed correctly: python3 -m vnc_collaborate should run with no output and no error

21. Install packages needed to run VNC desktops: sudo apt install fvwm tightvncserver ssvnc socat

    Only the window manager (FVWM), the VNC server, the VNC viewer (ssvnc), and socat are strictly required, 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. anything else you'd like to run on your desktops

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

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

24. Create UNIX user accounts for the students. No passwords need be set.

25. 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, UNIXuser text, 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.

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

    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)
    

27. 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)

28. 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:PORT/{jwt}

    If you're following the example, PORT is 6101.

    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.

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

30. 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 student access to the VNC desktops, but root and teacher (UID 1000 in this case) access is required:

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

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