galene
galene copied to clipboard
The Galène videoconference server
Galene is a videoconferencing server that is easy to deploy and requires moderate server resources. It is described at https://galene.org.
Installation
See the file INSTALL in this directory for installation instructions.
Usage
Locations
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.
Some statistics are available under /stats.json
, with a human-readable
version at /stats.html
. This is only available to the server administrator.
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.
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.
The global configuration file
The server may be configured in the JSON file data/config.json
. This
file may look as follows:
{
"canonicalHost": "galene.example.org",
"admin":[{"username":"root","password":"secret"}]
}
The fields are as follows:
-
canonicalHost
: the canonical name of the host running the server; -
admin
defines the users allowed to look at the/stats.html
file; it has the same syntax as user definitions in groups (see below).
Group definitions
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
groups/groupname.json
; it does not contain the group name, which makes
it easy to copy or link group definitions. You may use subdirectories:
a file groups/teaching/networking.json
defines a group called
teaching/networking.
A typical group definition file looks like this:
{
"op":[{"username":"jch","password":"1234"}],
"presenter":[{}],
"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
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:
-
op
,presenter
,other
: each of these is an array of user definitions (see Authorisation below) and specifies the users allowed to connect respectively with operator privileges, with presenter privileges, and as passive listeners; -
authKeys
,authServer
andauthPortal
: see Authorisation below; -
public
: if true, then the group is visible on the landing page; -
displayName
: a human-friendly version of the group name; -
description
: a human-readable description of the group; this is displayed on the landing page for public groups; -
contact
: a human-readable contact for this group, such as an e-mail address; -
comment
: a human-readable string; -
max-clients
: the maximum number of clients that may join the group at a time; -
max-history-age
: the time, in seconds, during which chat history is kept (default 14400, i.e. 4 hours); -
allow-recording
: if true, then recording is allowed in this group; -
allow-anonymous
: if true, then users may connect with an empty username; -
allow-subgroups
: if true, then subgroups of the formgroup/subgroup
are automatically created when first accessed; -
autolock
: if true, the group will start locked and become locked whenever there are no clients with operator privileges; -
autokick
: if true, all clients will be kicked out whenever there are no clients with operator privileges; this is not recommended, prefer theautolock
option instead; -
redirect
: if set, then attempts to join the group will be redirected to the given URL; most other fields are ignored in this case; -
codecs
: this is a list of codecs allowed in this group. The default is["vp8", "opus"]
.
Supported video codecs include:
-
"vp8"
(compatible with all supported browsers); -
"vp9"
(better video quality, but incompatible with Safari); -
"av1"
(even better video quality, only supported by some browsers, recording is not supported, SVC is not supported); -
"h264"
(incompatible with Debian and with some Android devices, SVC is not supported).
Supported audio codecs include "opus"
, "g722"
, "pcmu"
and "pcma"
.
Only Opus can be recorded to disk. There is no good reason to use
anything except Opus.
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
{"username": "jch", "password": "1234"}
specifies username jch with password 1234, while
{"password": "1234"}
allows any username with password 1234, and
{}
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
If you don't wish to store cleartext passwords on the server, you may
generate hashed passwords with the galene-password-generator
utility. A
user entry with a hashed password looks like this:
{
"username": "jch",
"password": {
"type": "pbkdf2",
"hash": "sha-256",
"key": "f591c35604e6aef572851d9c3543c812566b032b6dc083c81edd15cc24449913",
"salt": "92bff2ace56fe38f",
"iterations": 4096
}
}
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 specifies one or more public keys in JWK format. In addition, it may specify either an authorisation server or an authorisation portal.
{
"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"
}]
"authServer": "https://auth.example.org",
}
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.
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.
Further information
Galène's web page is at https://galene.org.
Answers to common questions and issues are at https://galene.org/faq.html.
-- Juliusz Chroboczek https://www.irif.fr/~jch/