Administration

Before we can actually start our first meeting, we need to add Tenants and Servers to our cluster. This can be fully automated via the API but for now, we will use the bbblb admin command line tool instead.

Note

If you followed the docker compose based deployment, you can use the bbblb.sh wrapper to run bbblb inside the container.

Manage Tenants

TODO

Adding new Tenants

To create your first "example" tenant, run:

bbblb tenant create --secret SECRET --realm bbb.example.com example

Replace SECRET with a suitable tenant secret, example with a short but meaningful tenant name, and bbb.example.com with the primary domain of your BBBLB instance.

Realms are used to associate API requests with tenants. BBBLB checks the request Host header by default and matches it against all configured tenants and their realms. Requests that do not have a matching tenant cannot be checksum-verified and are rejected.

In this example we associate the ‘example’ tenant with the primary domain. To add more tenants, associate each one with a unique domain or subdomain as their realm, so they can be told apart.

Override create or join parameters

The BBB APIs for creating or joining meetings accept a ton of parameters and allow front-ends to control features and other aspects on a per-meeting or per-user level. You can enforce or extend those parameters for each tenant using overrides:

bbblb override set TENANT create NAME=VALUE
bbblb override set TENANT join NAME=VALUE

You can define any number of create or join parameter overrides per tenant as PARAM=VALUE pairs. PARAM should match an API parameter you want to override, and the given VALUE will be enforced on all future create or join calls issued by this tenant. If VALUE is empty, then the parameter will be removed from future API calls.

Instead of the = operator you can also use ? to define a default value instead of an override, < to define a maximum value for numeric parameters (e.g. duration, maxParticipants), or + to add items to a comma separated list parameter (e.g. disabledFeatures).

Examples:

# Limit the 'free' tenant to 100 participants and 90 minutes
# per meeting, and prevent recordings
bbblb override free create "duration<90" "maxParticipants<100" "record="

# Set a different default presentation for the 'moodle' tenant
bbblb override moodle create "preUploadedPresentation?https://dl.example.com/school1.pdf"

# Disable chat for the 'interview' tenant
bbblb override interview create "disabledFeatures+chat" "disabledFeaturesExclude="

Manage Servers

TODO

Adding new Servers

Let's assume you already have some BBB servers up and running.

Attention

Make sure to install the ./examples/post_publish_bbblb.rb script on BBB servers before using them in your cluster, or recordings won’t be transferred.

To attach your first BBB server, run:

bbblb server create --secret=SECRET server1.example.com

Replace SECRET with the BBB server API secret and server1.example.com with its domain.

It may take up to 50 seconds (5 times the poll interval default) until the server is actually available for new meetings. Check ./bbblb.sh server list to see all servers and their state.

That’s it. Your ‘example’ tenant should now be able to start and manage meetings in your cluster via BBBLB.

Manage Recordings

TODO

Import old Recordings

You can import existing recordings and assign them to a tenant with the bbblb CLI:

Usage: bbblb recording import --tenant TENANT FILE

The FILE parameter should point to a .tar or .tgz archive containing the recording data. If missing or -, the command will read from standard input, which is most useful when BBBLB runs within a container that may not see the files you want to import:

tar -c /path/to/presentation/ | bbblb recording import --tenant mytenant -

The tar file can actually contain multiple recordings. Every directory with a metadata.xml will be imported.

Mass-Import Recordings

If you have a lot of recordings and the 'standard' way to import them one by one is too slow, there is another way. It's more efficient and way quicker, but also more involved because you now have to do half of the steps yourself and there is no safety net. Only do this if you know what you are doing. Here is how:

  • Copy each unpacked recording into the corresponding storage directory ({PATH_DATA}/recordings/storage/<tenant>/<record_id>/<format>/...).

    • Note the order of ../<record_id>/<format>/.., which is different from the way BBB or Scalelite store recordings.

    • Make sure the file permissions are correct. BBBLB should be the owner of all files and directories.

  • Then run recording check-database without any checks to see if it can find the new recordings.

  • Then run the command again with the --fix-missing switch to actually import any recordings that are on disk and not in the database yet.

  • Then run recording publish for all of the imported recording IDs to publish them.

This is also a good way to mass-delete recordings, or mass-move recordings to a new tenant. Do the work in the storage directory yourself, then use the recording check-database command to fix the database.

Sync Cluster State

A BBBLB cluster is mostly defined by the configured servers and tenants. If both change frequently in your environment, you may want to automate cluster management.

BBBLB offers a way to export and later import the entire cluster state (servers and tenants) as JSON files. This can be used for backup, but also to sync the cluster state with a JSON state file generated by automation.

# Export state to cluster.json
bbblb state export > cluster.json

# TODO: Modify or generate cluster.json with your own tooling

# Check what would need to change so the state matches cluster.json
bbblb state import --dry-run < cluster.json
# Actually change the cluster state to match cluster.json
bbblb state import --delete --nuke < cluster.json

By default, servers and tenants not present in the input file will only be disabled and not removed. You can force the removal of empty servers with the --delete switch. Servers or tenants that have running meetings are still not removed by default, because that would cause many issues. The --nuke switch takes care of that by force-ending all affected meetings. If unsure, use the --dry-run switch to check what would happen without actually applying any changes or ending any meetings.

Export format

The export file format is stable and backwards compatible within major releases of BBBLB.

{
    "v": 1,
    "servers": {
        "bbb01.example.com": {
            "enabled": true
            "secret": "supersecret",
        }
    },
    "tenants": {
        "mytenant": {
            "enabled": true,
            "secret": "superdupersecret",
            "realm": "bbblb.example.com",
            "overrides": {
                "create": {
                    "maxParticipants": "<100"
                }
            }
        }
    }
}

The state file format is versioned, and BBBLB can usually import old versions just fine. It will always generate the most recent version, though.

Automate with Ansible

One way to use this is to generated the file with tools like ansible and then import the desired state into BBBLB with a single atomic and idempotent command.

Here is an example ansible playbook that shows how this could look like (untested):

---
- name: Sync BBBLB state
  hosts: bbblb.example.com
  vars:
    cluster:
      servers:
        bbb1.example.com:
          enabled: True
          secret: supersecret
      tenants:
        mytenant:
          enabled: True
          secret: superdupersecret
          realm: bbblb.example.com
          overrides:
            create:
              maxParticipants: "<100"
  tasks:
    - name: Sync cluster state
      ansible.builtin.command:
        chdir: /path/to/bbblb/
        cmd: bbblb state import --delete
        stdin: "{{ cluster | to_json(indent=2) }}"
      register: state_sync
      changed_when: "'Nothing to do' not in state_sync.stdout"

Please note that I did not actually test this with ansible, it's just here to get you an idea.