2021-12-01 23:42:10 +01:00
|
|
|
|
Galene is a videoconferencing server that is easy to deploy and requires
|
|
|
|
|
moderate server resources. It is described at <https://galene.org>.
|
|
|
|
|
|
|
|
|
|
|
2020-05-29 17:49:23 +02:00
|
|
|
|
# Installation
|
|
|
|
|
|
2021-08-06 16:59:46 +02:00
|
|
|
|
See the file INSTALL in this directory for installation instructions.
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
# Usage
|
|
|
|
|
|
|
|
|
|
## Locations
|
2020-05-31 23:16:08 +02:00
|
|
|
|
|
|
|
|
|
There is a landing page at the root of the server. It contains a form
|
|
|
|
|
for typing the name of a group, and a clickable list of public groups.
|
|
|
|
|
|
|
|
|
|
Groups are available under `/group/groupname`. You may share this URL
|
|
|
|
|
with others, there is no need to go through the landing page.
|
|
|
|
|
|
|
|
|
|
Recordings can be accessed under `/recordings/groupname`. This is only
|
|
|
|
|
available to the administrator of the group.
|
|
|
|
|
|
2021-04-30 20:33:23 +02:00
|
|
|
|
Some statistics are available under `/stats.json`, with a human-readable
|
|
|
|
|
version at `/stats.html`. This is only available to the server administrator.
|
2020-05-31 23:16:08 +02:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
## Side menu
|
|
|
|
|
|
|
|
|
|
There is a menu on the right of the user interface. This allows choosing
|
|
|
|
|
the camera and microphone and setting the video throughput. The
|
|
|
|
|
*Blackboard mode* checkbox increases resolution and sacrifices framerate
|
|
|
|
|
in favour of image quality. The *Play local file* dialog allows streaming
|
|
|
|
|
a video from a local file.
|
2020-05-31 23:16:08 +02:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
## Commands
|
|
|
|
|
|
|
|
|
|
Typing a line starting with a slash `/` in the chat dialogue causes
|
|
|
|
|
a command to be sent to the server. Type `/help` to get the list of
|
|
|
|
|
available commands; the output depends on whether you are an operator or
|
|
|
|
|
not.
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
|
|
|
|
|
2021-10-26 20:10:24 +02:00
|
|
|
|
# The global configuration file
|
|
|
|
|
|
|
|
|
|
The server may be configured in the JSON file `data/config.json`. This
|
|
|
|
|
file may look as follows:
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"admin":[{"username":"root","password":"secret"}]
|
2022-10-21 13:28:11 +02:00
|
|
|
|
"canonicalHost": "galene.example.org",
|
2021-10-26 20:10:24 +02:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
The fields are as follows:
|
|
|
|
|
|
2022-10-21 13:28:11 +02:00
|
|
|
|
- `proxyURL`: if running behind a reverse proxy, this specifies the
|
|
|
|
|
address of the proxy.
|
2021-10-26 20:10:24 +02:00
|
|
|
|
- `admin` defines the users allowed to look at the `/stats.html` file; it
|
|
|
|
|
has the same syntax as user definitions in groups (see below).
|
2022-10-21 13:28:11 +02:00
|
|
|
|
- `canonicalHost`: the canonical name of the host running the server; this
|
|
|
|
|
will cause clients to be redirected if they use a different hostname to
|
|
|
|
|
access the server.
|
2021-10-26 20:10:24 +02:00
|
|
|
|
|
|
|
|
|
|
2021-08-06 16:59:46 +02:00
|
|
|
|
# Group definitions
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
Groups are defined by files in the `./groups` directory (this may be
|
|
|
|
|
configured by the `-groups` command-line option, try `./galene -help`).
|
|
|
|
|
The definition for the group called *groupname* is in the file
|
2021-01-26 22:59:19 +01:00
|
|
|
|
`groups/groupname.json`; it does not contain the group name, which makes
|
2021-01-08 15:36:23 +01:00
|
|
|
|
it easy to copy or link group definitions. You may use subdirectories:
|
|
|
|
|
a file `groups/teaching/networking.json` defines a group called
|
2021-05-22 16:58:09 +02:00
|
|
|
|
*teaching/networking*.
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
2021-08-06 16:59:46 +02:00
|
|
|
|
A typical group definition file looks like this:
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"op":[{"username":"jch","password":"1234"}],
|
2022-03-08 16:06:58 +01:00
|
|
|
|
"presenter":[{}],
|
2021-08-06 16:59:46 +02:00
|
|
|
|
"allow-recording": true,
|
|
|
|
|
"allow-subgroups": true
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
This defines a group with the operator (administrator) username *jch* and
|
|
|
|
|
password *1234*, empty username and password for presenters (ordinary
|
|
|
|
|
users with the right to enable their camera and microphone). The
|
|
|
|
|
`allow-recording` entry says that the operator is allowed to record videos
|
|
|
|
|
to disk, and the `allow-subgroups` entry says that subgroups will be
|
|
|
|
|
created automatically.
|
|
|
|
|
|
|
|
|
|
More precisely, every group definition file contains a single JSON
|
|
|
|
|
directory (a list of entries between `{' and `}'). All fields are
|
2021-01-26 22:59:19 +01:00
|
|
|
|
optional, but unless you specify at least one user definition (`op`,
|
|
|
|
|
`presenter`, or `other`), nobody will be able to join the group. The
|
|
|
|
|
following fields are allowed:
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
|
|
|
|
- `op`, `presenter`, `other`: each of these is an array of user
|
2021-10-29 23:37:05 +02:00
|
|
|
|
definitions (see *Authorisation* below) and specifies the users allowed
|
|
|
|
|
to connect respectively with operator privileges, with presenter
|
|
|
|
|
privileges, and as passive listeners;
|
2022-02-19 23:58:31 +01:00
|
|
|
|
- `authKeys`, `authServer` and `authPortal`: see *Authorisation* below;
|
2020-05-30 01:18:00 +02:00
|
|
|
|
- `public`: if true, then the group is visible on the landing page;
|
2021-07-16 19:41:00 +02:00
|
|
|
|
- `displayName`: a human-friendly version of the group name;
|
2020-09-24 22:03:41 +02:00
|
|
|
|
- `description`: a human-readable description of the group; this is
|
|
|
|
|
displayed on the landing page for public groups;
|
2021-01-13 23:00:48 +01:00
|
|
|
|
- `contact`: a human-readable contact for this group, such as an e-mail
|
|
|
|
|
address;
|
|
|
|
|
- `comment`: a human-readable string;
|
2020-05-29 17:49:23 +02:00
|
|
|
|
- `max-clients`: the maximum number of clients that may join the group at
|
|
|
|
|
a time;
|
2020-10-08 14:38:33 +02:00
|
|
|
|
- `max-history-age`: the time, in seconds, during which chat history is
|
|
|
|
|
kept (default 14400, i.e. 4 hours);
|
2020-05-30 01:18:00 +02:00
|
|
|
|
- `allow-recording`: if true, then recording is allowed in this group;
|
2021-01-08 15:36:23 +01:00
|
|
|
|
- `allow-anonymous`: if true, then users may connect with an empty username;
|
2020-11-22 19:54:54 +01:00
|
|
|
|
- `allow-subgroups`: if true, then subgroups of the form `group/subgroup`
|
2021-01-08 15:36:23 +01:00
|
|
|
|
are automatically created when first accessed;
|
2021-01-14 03:56:37 +01:00
|
|
|
|
- `autolock`: if true, the group will start locked and become locked
|
|
|
|
|
whenever there are no clients with operator privileges;
|
2021-01-17 21:29:07 +01:00
|
|
|
|
- `autokick`: if true, all clients will be kicked out whenever there are
|
2021-01-17 21:52:26 +01:00
|
|
|
|
no clients with operator privileges; this is not recommended, prefer
|
|
|
|
|
the `autolock` option instead;
|
2020-09-10 13:55:57 +02:00
|
|
|
|
- `redirect`: if set, then attempts to join the group will be redirected
|
2021-01-08 15:36:23 +01:00
|
|
|
|
to the given URL; most other fields are ignored in this case;
|
2020-12-25 17:33:44 +01:00
|
|
|
|
- `codecs`: this is a list of codecs allowed in this group. The default
|
2021-01-08 15:36:23 +01:00
|
|
|
|
is `["vp8", "opus"]`.
|
|
|
|
|
|
|
|
|
|
Supported video codecs include:
|
|
|
|
|
|
|
|
|
|
- `"vp8"` (compatible with all supported browsers);
|
2021-04-25 00:09:49 +02:00
|
|
|
|
- `"vp9"` (better video quality, but incompatible with Safari);
|
|
|
|
|
- `"av1"` (even better video quality, only supported by some browsers,
|
2021-07-30 13:55:04 +02:00
|
|
|
|
recording is not supported, SVC is not supported);
|
2021-07-30 16:02:36 +02:00
|
|
|
|
- `"h264"` (incompatible with Debian and with some Android devices, SVC
|
2021-07-30 13:55:04 +02:00
|
|
|
|
is not supported).
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
Supported audio codecs include `"opus"`, `"g722"`, `"pcmu"` and `"pcma"`.
|
2021-07-30 13:55:04 +02:00
|
|
|
|
Only Opus can be recorded to disk. There is no good reason to use
|
|
|
|
|
anything except Opus.
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
|
|
|
|
|
## Client Authorisation
|
|
|
|
|
|
|
|
|
|
Galene implements two authorisation methods: a simple username/password
|
|
|
|
|
authorisation scheme that is built into the Galene server, and
|
|
|
|
|
a token-based mechanism that relies on an external server. The simple
|
|
|
|
|
mechanism is intended to be used in standalone installations, while the
|
|
|
|
|
server-based mechanism is designed to allow easy integration with an
|
|
|
|
|
existing authorisation infrastructure (such as LDAP, OAuth2, or even Unix
|
|
|
|
|
passwords).
|
|
|
|
|
|
|
|
|
|
### Password authorisation
|
|
|
|
|
|
|
|
|
|
When password authorisation is used, authorised usernames and password are
|
|
|
|
|
defined directly in the group configuration file, in the `op`, `presenter`
|
|
|
|
|
and `other` arrays. Each member of the array is a dictionary, that may
|
|
|
|
|
contain the fields `username` and `password`:
|
|
|
|
|
|
|
|
|
|
- if `username` is present, then the entry only matches clients that
|
|
|
|
|
specify this exact username; otherwise, any username matches;
|
|
|
|
|
- if `password` is present, then the entry only matches clients that
|
|
|
|
|
specify this exact password; otherwise, any password matches.
|
|
|
|
|
|
|
|
|
|
For example, the entry
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
{"username": "jch", "password": "1234"}
|
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
specifies username *jch* with password *1234*, while
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
{"password": "1234"}
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
allows any username with password *1234*, and
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
{}
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
allows any username with any password.
|
|
|
|
|
|
|
|
|
|
By default, empty usernames are forbidden; set the `allow-anonymous`
|
|
|
|
|
option to allow empty usernames. By default, recording is forbidden;
|
|
|
|
|
specify the `allow-recording` option to allow operators to record.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Hashed passwords
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
If you don't wish to store cleartext passwords on the server, you may
|
2021-10-29 23:37:05 +02:00
|
|
|
|
generate hashed passwords with the `galene-password-generator` utility. A
|
2021-01-08 15:36:23 +01:00
|
|
|
|
user entry with a hashed password looks like this:
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2020-11-29 14:26:42 +01:00
|
|
|
|
{
|
|
|
|
|
"username": "jch",
|
|
|
|
|
"password": {
|
|
|
|
|
"type": "pbkdf2",
|
|
|
|
|
"hash": "sha-256",
|
|
|
|
|
"key": "f591c35604e6aef572851d9c3543c812566b032b6dc083c81edd15cc24449913",
|
|
|
|
|
"salt": "92bff2ace56fe38f",
|
|
|
|
|
"iterations": 4096
|
|
|
|
|
}
|
|
|
|
|
}
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
### Authorisation servers
|
|
|
|
|
|
|
|
|
|
Galene is able to delegate authorisation decisions to an external
|
|
|
|
|
authorisation server. This makes it possible to integrate Galene with an
|
|
|
|
|
existing authentication and authorisation infrastructure, such as LDAP,
|
|
|
|
|
OAuth2 or even Unix passwords.
|
|
|
|
|
|
|
|
|
|
When an authorisation server is used, the group configuration file
|
2022-02-19 23:58:31 +01:00
|
|
|
|
specifies one or more public keys in JWK format. In addition, it may
|
|
|
|
|
specify either an authorisation server or an authorisation portal.
|
2021-10-29 23:37:05 +02:00
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"authKeys": [{
|
|
|
|
|
"kty": "oct",
|
|
|
|
|
"alg": "HS256",
|
|
|
|
|
"k": "MYz3IfCq4Yq-UmPdNqWEOdPl4C_m9imHHs9uveDUJGQ",
|
|
|
|
|
"kid": "20211030"
|
|
|
|
|
}, {
|
|
|
|
|
"kty": "EC",
|
|
|
|
|
"alg": "ES256",
|
|
|
|
|
"crv": "P-256",
|
|
|
|
|
"x": "dElK9qBNyCpRXdvJsn4GdjrFzScSzpkz_I0JhKbYC88",
|
|
|
|
|
"y": "pBhVb37haKvwEoleoW3qxnT4y5bK35_RTP7_RmFKR6Q",
|
|
|
|
|
"kid": "20211101"
|
|
|
|
|
}]
|
2022-02-19 23:58:31 +01:00
|
|
|
|
"authServer": "https://auth.example.org",
|
2021-10-29 23:37:05 +02:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
The `kid` field serves to distinguish among multiple keys, and must match
|
|
|
|
|
the value provided by the authorisation server. If the server doesn't
|
|
|
|
|
provide a `kid`, the first key with a matching `alg` field will be used.
|
|
|
|
|
|
2022-02-19 23:58:31 +01:00
|
|
|
|
If an authorisation server is specified, then the default client, after it
|
|
|
|
|
prompts for a password, will request a token from the authorisation server
|
|
|
|
|
and will join the group using token authentication. The password is never
|
|
|
|
|
communicated to the server.
|
|
|
|
|
|
|
|
|
|
If an authorisation portal is specified, then the default client will
|
|
|
|
|
redirect initial client connections to the authorisation portal. The
|
|
|
|
|
authorisation portal is expected to authorise the client and then redirect
|
|
|
|
|
it to Galene with the `username` and `token` query parameters set.
|
|
|
|
|
|
2021-10-29 23:37:05 +02:00
|
|
|
|
|
2021-01-24 16:57:26 +01:00
|
|
|
|
# Further information
|
|
|
|
|
|
|
|
|
|
Galène's web page is at <https://galene.org>.
|
|
|
|
|
|
2021-08-02 02:50:29 +02:00
|
|
|
|
Answers to common questions and issues are at <https://galene.org/faq.html>.
|
2021-01-24 16:57:26 +01:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-18 20:24:52 +01:00
|
|
|
|
-- Juliusz Chroboczek <https://www.irif.fr/~jch/>
|