==============
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 :doc:`API <api>` but for now, we will use the ``bbblb`` admin command line tool instead.

.. note::

    If you followed the :doc:`docker compose based deployment <install>`, 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:

.. code:: bash

    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:

.. code:: bash

   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

.. _migrate-recordings:

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 :ref:`cli-bbblb-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 :ref:`cli-bbblb-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 :ref:`cli-bbblb-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.

.. code:: bash

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

.. code:: json

    {
        "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 <https://docs.ansible.com>`_
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):

.. code:: yaml

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