mirror of
https://github.com/jech/galene.git
synced 2024-12-22 15:25:48 +01:00
98235afe06
Make the de-facto "comment" and "contact" fields official.
291 lines
9.2 KiB
Text
291 lines
9.2 KiB
Text
# Installation
|
||
|
||
## Build the server binary
|
||
|
||
CGO_ENABLED=0 go build -ldflags='-s -w'
|
||
|
||
## Create a server certificate
|
||
|
||
mkdir data
|
||
openssl req -newkey rsa:2048 -nodes -keyout data/key.pem -x509 -days 365 -out data/cert.pem
|
||
|
||
## Set the server administrator credentials
|
||
|
||
This step is optional.
|
||
|
||
echo 'god:topsecret' > data/passwd
|
||
|
||
## Set up an ICE server
|
||
|
||
ICE is the NAT and firewall traversal protocol used by WebRTC. ICE uses
|
||
a variety of techniques for establishing a flow in the presence of
|
||
a firewall; the two most effective techniques, STUN and TURN, require help
|
||
from an external server. Whether you need a helping server depends both
|
||
on your firewalling setup and on the networks of your users; for
|
||
production use, you should probably use your own TURN server.
|
||
|
||
### No ICE server
|
||
|
||
If Galène is not firewalled (high-numbered ports are accessible from the
|
||
Internet) and none of your users are on a restrictive network, then you
|
||
need no ICE servers. There is nothing to do, skip to *Set up a group*
|
||
below.
|
||
|
||
### STUN server
|
||
|
||
If Galène might be behind a firewall (high-numbered ports might or might
|
||
not be accessible from the Internet), but none of your clients are on
|
||
a restrictive network, then a STUN server is enough. It is usually safe
|
||
to use a third-party STUN server, although doing that might violate the
|
||
privacy of your users. Your `data/ice-servers.json` file should look like
|
||
this:
|
||
|
||
[
|
||
{
|
||
"urls": [
|
||
"stun:stun.example.org"
|
||
]
|
||
}
|
||
]
|
||
|
||
### TURN server
|
||
|
||
In practice, some of your users will be on restrictive networks: many
|
||
enterprise networks only allow outgoing TCP to ports 80 and 443;
|
||
university networks tend to additionally allow outgoing traffic to port
|
||
1194. For best performance, your TURN server should be located close to
|
||
Galène and close to your users, so you will want to run your own (I use
|
||
*coturn*, but other implementations of TURN should work too).
|
||
|
||
Your `ice-servers.json` should look like this, where `username` and
|
||
`secret` are identical to the ones in your TURN server's configuration:
|
||
|
||
[
|
||
{
|
||
"urls": [
|
||
"turn:turn.example.org:443",
|
||
"turn:turn.example.org:443?transport=tcp"
|
||
],
|
||
"username": "galene",
|
||
"credential": "secret"
|
||
}
|
||
]
|
||
|
||
If you use coturn's `use-auth-secret` option, then your `ice-servers.json`
|
||
should look like this:
|
||
|
||
[
|
||
{
|
||
"urls": [
|
||
"turn:turn.example.com:443",
|
||
"turn:turn.example.com:443?transport=tcp"
|
||
],
|
||
"username": "galene",
|
||
"credential": "secret",
|
||
"credentialType": "hmac-sha1"
|
||
}
|
||
]
|
||
|
||
For redundancy, you may set up multiple TURN servers, and ICE will use the
|
||
first one that works.
|
||
|
||
## Set up a group
|
||
|
||
A group is set up by creating a file `groups/name.json`.
|
||
|
||
mkdir groups
|
||
vi groups/groupname.json
|
||
|
||
A group with a single operator and no password for ordinary users looks
|
||
like this:
|
||
|
||
{
|
||
"op": [{"username": "jch", "password": "1234"}],
|
||
"presenter": [{}]
|
||
}
|
||
|
||
A group with one operator and two users looks like this:
|
||
|
||
{
|
||
"op": [{"username": "jch", "password": "1234"}],
|
||
"presenter": [
|
||
{"username": "mom", "password": "0000"},
|
||
{
|
||
"username": "dad",
|
||
"password": "Pójdźże, kiń tę chmurność w głąb flaszy!"
|
||
}
|
||
]
|
||
}
|
||
|
||
More options are described under *Details of group definitions* below.
|
||
|
||
## Test locally
|
||
|
||
./galene &
|
||
|
||
You should be able to access Galène at `https://localhost:8443`. Connect
|
||
to the group that you have just set up in two distinct browser windows,
|
||
then press *Ready* in one of the two; you should see a video in the other.
|
||
|
||
If you have set up a TURN server, type */relay-test* in the chat box; if
|
||
the TURN server is properly configured, you should see a message saying
|
||
that the relay test has been successful. (The relay test will fail if you
|
||
didn't configure a TURN server; this is normal, and nothing to worry
|
||
about.)
|
||
|
||
## Deploy to your server
|
||
|
||
Set up a user *galene* on your server, then do:
|
||
|
||
rsync -a galene static data groups galene@server.example.org:
|
||
|
||
Now run the binary on the server:
|
||
|
||
ssh galene@server.example.org
|
||
ulimit -n 65536
|
||
nohup ./galene &
|
||
|
||
If you are using *runit*, use a script like the following:
|
||
|
||
#!/bin/sh
|
||
exec 2>&1
|
||
cd ~galene
|
||
ulimit -n 65536
|
||
exec setuidgid galene ./galene
|
||
|
||
If you are using *systemd*:
|
||
|
||
[Unit]
|
||
Description=Galene
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
WorkingDirectory=/home/galene
|
||
User=galene
|
||
Group=galene
|
||
ExecStart=/home/galene/galene
|
||
LimitNOFILE=65536
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
|
||
# 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`. 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.
|
||
|
||
|
||
# Details of 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` and 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
|
||
*teching/networking*.
|
||
|
||
Every group definition file contains a JSON directory with the following
|
||
fields. 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.
|
||
|
||
- `op`, `presenter`, `other`: each of these is an array of user
|
||
definitions (see below) and specifies the users allowed to connect
|
||
respectively with operator privileges, with presenter privileges, and
|
||
as passive listeners;
|
||
- `public`: if true, then the group is visible on the landing page;
|
||
- `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 form `group/subgroup`
|
||
are automatically created when first accessed;
|
||
- `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 than `"vp8"`, but incompatible with
|
||
older versions of Mac OS);
|
||
- `"h264"` (incompatible with Debian, Ubuntu, and some Android devices,
|
||
recording is not supported).
|
||
|
||
Supported audio codecs include `"opus"`, `"g722"`, `"pcmu"` and `"pcma"`.
|
||
There is no good reason to use anything except Opus.
|
||
|
||
A user definition is a dictionary with the following fields:
|
||
|
||
- `username`: the username of the user; if omitted, any username is
|
||
allowed;
|
||
- `password`: if omitted, then no password is required. Otherwise, this
|
||
can either be a string, specifying a plain text password, or
|
||
a dictionary generated by the `galene-password-generator` utility.
|
||
|
||
For example,
|
||
|
||
{"username": "jch", "password": "1234"}
|
||
|
||
specifies user *jch* with password *1234*, while
|
||
|
||
{"password": "1234"}
|
||
|
||
specifies that any (non-empty) username will do, and
|
||
|
||
{}
|
||
|
||
allows any (non-empty) username with any password.
|
||
|
||
If you don't wish to store cleartext passwords on the server, you may
|
||
generate hashed password 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
|
||
}
|
||
}
|
||
|
||
--- Juliusz Chroboczek <https://www.irif.fr/~jch/>
|