2020-05-29 17:49:23 +02:00
|
|
|
|
# Installation
|
|
|
|
|
|
2021-03-03 00:03:44 +01:00
|
|
|
|
## Build the `galene` binary
|
|
|
|
|
|
|
|
|
|
You will need Go 1.13 or later (type `go version`). Then do:
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 go build -ldflags='-s -w'
|
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
On Windows, do
|
|
|
|
|
|
|
|
|
|
set CGO_ENABLED=0
|
2021-07-04 15:07:12 +02:00
|
|
|
|
go build -ldflags="-s -w"
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
|
|
|
|
|
2020-09-24 19:08:25 +02:00
|
|
|
|
## Set the server administrator credentials
|
|
|
|
|
|
|
|
|
|
This step is optional.
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
2021-02-24 20:01:48 +01:00
|
|
|
|
mkdir data
|
2020-04-29 18:31:54 +02:00
|
|
|
|
echo 'god:topsecret' > data/passwd
|
|
|
|
|
|
2020-09-24 19:08:25 +02:00
|
|
|
|
## Set up a group
|
|
|
|
|
|
2021-01-26 22:59:19 +01:00
|
|
|
|
A group called *groupname* is is set up by creating a file
|
|
|
|
|
`groups/groupname.json`.
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
|
|
|
|
mkdir groups
|
2021-01-08 15:36:23 +01:00
|
|
|
|
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:
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
|
|
|
|
{
|
2021-01-08 15:36:23 +01:00
|
|
|
|
"op": [{"username": "jch", "password": "1234"}],
|
|
|
|
|
"presenter": [
|
|
|
|
|
{"username": "mom", "password": "0000"},
|
2021-01-18 20:24:52 +01:00
|
|
|
|
{"username": "dad", "password": "1234"}
|
2021-01-08 15:36:23 +01:00
|
|
|
|
]
|
2020-04-29 18:31:54 +02:00
|
|
|
|
}
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
More options are described under *Details of group definitions* below.
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
## Test locally
|
2020-09-24 19:08:25 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
./galene &
|
|
|
|
|
|
2021-01-11 19:33:09 +01:00
|
|
|
|
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.
|
|
|
|
|
|
2021-01-18 20:24:52 +01:00
|
|
|
|
## Configure your server's firewall
|
|
|
|
|
|
|
|
|
|
If your server has a global IPv4 address and there is no firewall, there
|
|
|
|
|
is nothing to do.
|
|
|
|
|
|
|
|
|
|
If your server has a global IPv4 address, then the firewall must, at
|
|
|
|
|
a strict minimum, allow incoming traffic to TCP port 8443 (or whatever is
|
|
|
|
|
configured with the `-http` command-line option) and TCP port 1194 (or
|
2021-05-10 23:24:18 +02:00
|
|
|
|
whatever is configured with the `-turn` option). For best performance, it
|
|
|
|
|
should also allow UDP traffic to the TURN port, and UDP traffic to
|
|
|
|
|
ephemeral (high-numbered) ports (or whatever is configured using the
|
|
|
|
|
`-udp-range` option).
|
2021-01-18 20:24:52 +01:00
|
|
|
|
|
2021-07-04 15:07:12 +02:00
|
|
|
|
If your server is behind NAT (which is not recommended), then the NAT must
|
|
|
|
|
forward, at the very least, port 8443 to your server. Ideally, you should
|
|
|
|
|
configure an external TURN server (see *ICE Servers* below) on a host that
|
|
|
|
|
is not behind NAT. If that is not possible, then you must use a NAT that
|
|
|
|
|
supports hairpinning, you must forward port 1194 in addition to port 8443,
|
|
|
|
|
and you will need to add add the option `-turn 203.0.113.1:1194` to
|
|
|
|
|
Galène's command line, where `203.0.113.1` is your NAT's external (global)
|
|
|
|
|
IPv4 address.
|
2021-01-18 20:24:52 +01:00
|
|
|
|
|
|
|
|
|
|
2021-01-25 17:47:59 +01:00
|
|
|
|
## Cross-compile for your server
|
|
|
|
|
|
2021-03-03 00:03:44 +01:00
|
|
|
|
This step is only required if your server runs a different OS or has
|
|
|
|
|
a different CPU than your build machine.
|
2021-01-25 17:47:59 +01:00
|
|
|
|
|
|
|
|
|
For a Linux server with an Intel or AMD CPU:
|
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags='-s -w'
|
|
|
|
|
|
|
|
|
|
For a Raspberry Pi 1:
|
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -ldflags='-s -w'
|
|
|
|
|
|
|
|
|
|
For a BeagleBone or a Raspberry Pi 2 or later:
|
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -ldflags='-s -w'
|
|
|
|
|
|
2021-07-04 15:07:12 +02:00
|
|
|
|
For a 64-bit ARM board (Olimex Olinuxino-A64, Pine64, etc.) or server:
|
2021-01-25 17:47:59 +01:00
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags='-s -w'
|
|
|
|
|
|
|
|
|
|
For a 32-bit MIPS board with no hardware floating point (WNDR3800, etc.):
|
|
|
|
|
|
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=mips GOMIPS=softfloat go build -ldflags='-s -w'
|
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
## Deploy to your server
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
Set up a user *galene* on your server, then do:
|
|
|
|
|
|
|
|
|
|
rsync -a galene static data groups galene@server.example.org:
|
2021-02-24 20:01:48 +01:00
|
|
|
|
|
|
|
|
|
If you don't have a TLS certificate, Galène will generate a self-signed
|
|
|
|
|
certificate automatically (and print a warning to the logs). If you have
|
|
|
|
|
a certificate, install it in the files `data/cert.pem` and `data/key.pem`:
|
|
|
|
|
|
2021-02-27 14:27:48 +01:00
|
|
|
|
ssh galene@server.example.org
|
|
|
|
|
sudo cp /etc/letsencrypt/live/server.example.org/fullchain.pem data/cert.pem
|
2021-07-04 15:07:12 +02:00
|
|
|
|
sudo cp /etc/letsencrypt/live/server.example.org/privkey.pem data/key.pem
|
2021-02-27 14:27:48 +01:00
|
|
|
|
sudo chown galene:galene data/*.pem
|
|
|
|
|
sudo chmod go-rw data/key.pem
|
2021-01-08 15:36:23 +01:00
|
|
|
|
|
|
|
|
|
Now run the binary on the server:
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
2020-12-06 19:43:17 +01:00
|
|
|
|
ssh galene@server.example.org
|
2021-01-08 15:36:23 +01:00
|
|
|
|
ulimit -n 65536
|
2020-12-06 19:43:17 +01:00
|
|
|
|
nohup ./galene &
|
2020-04-29 18:31:54 +02:00
|
|
|
|
|
2020-09-24 19:08:25 +02:00
|
|
|
|
If you are using *runit*, use a script like the following:
|
|
|
|
|
|
|
|
|
|
#!/bin/sh
|
|
|
|
|
exec 2>&1
|
2020-12-06 19:43:17 +01:00
|
|
|
|
cd ~galene
|
2020-12-19 02:37:07 +01:00
|
|
|
|
ulimit -n 65536
|
2020-12-06 19:43:17 +01:00
|
|
|
|
exec setuidgid galene ./galene
|
2020-09-24 19:08:25 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
If you are using *systemd*:
|
2020-12-19 02:37:07 +01:00
|
|
|
|
|
|
|
|
|
[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
|
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-01-08 15:36:23 +01:00
|
|
|
|
# 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
|
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-01-26 22:59:19 +01:00
|
|
|
|
Every group definition file contains a JSON directory. 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:
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
|
|
|
|
- `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;
|
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,
|
|
|
|
|
recording is not supported);
|
2021-01-08 15:36:23 +01:00
|
|
|
|
- `"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.
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
|
|
|
|
A user definition is a dictionary with the following fields:
|
|
|
|
|
|
|
|
|
|
- `username`: the username of the user; if omitted, any username is
|
|
|
|
|
allowed;
|
2020-11-29 14:26:42 +01:00
|
|
|
|
- `password`: if omitted, then no password is required. Otherwise, this
|
|
|
|
|
can either be a string, specifying a plain text password, or
|
2020-12-06 19:43:17 +01:00
|
|
|
|
a dictionary generated by the `galene-password-generator` utility.
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2020-11-29 14:26:42 +01:00
|
|
|
|
For example,
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
{"username": "jch", "password": "1234"}
|
|
|
|
|
|
|
|
|
|
specifies user *jch* with password *1234*, while
|
|
|
|
|
|
|
|
|
|
{"password": "1234"}
|
2020-05-29 17:49:23 +02:00
|
|
|
|
|
2021-01-08 15:36:23 +01:00
|
|
|
|
specifies that any (non-empty) username will do, 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-01-08 15:36:23 +01:00
|
|
|
|
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:
|
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-01-18 20:24:52 +01:00
|
|
|
|
# ICE Servers
|
|
|
|
|
|
|
|
|
|
ICE is the NAT and firewall traversal protocol used by WebRTC. ICE can
|
|
|
|
|
make use of two kinds of servers to help with NAT traversal: STUN servers,
|
2021-01-26 22:59:19 +01:00
|
|
|
|
that help punching holes in well-behaved NATs, and TURN servers, that
|
|
|
|
|
serve as relays for traffic. TURN is a superset of STUN: no STUN server
|
|
|
|
|
is necessary if a TURN server is available.
|
2021-01-18 20:24:52 +01:00
|
|
|
|
|
2021-01-26 22:59:19 +01:00
|
|
|
|
Galène includes an IPv4-only TURN server, which is controlled by the
|
2021-01-19 18:04:39 +01:00
|
|
|
|
`-turn` command-line option. If its value is set to the empty string
|
|
|
|
|
`""`, then the built-in server is disabled. If its value is a colon
|
|
|
|
|
followed with a port number, for example `:1194`, then the TURN server
|
|
|
|
|
will listen on all public IPv4 addresses of the local host, over UDP and
|
|
|
|
|
TCP. If the value of this option is a socket address, such as
|
2021-01-26 22:59:19 +01:00
|
|
|
|
`203.0.113.1:1194`, then the TURN server will listen on all addresses of
|
|
|
|
|
the local host but assume that the address seen by the clients is the one
|
|
|
|
|
given in the option; this is useful when running behind NAT with port
|
|
|
|
|
forwarding set up. The default value is `-turn auto`, which starts a
|
|
|
|
|
TURN server on port 1194 unless there is a `data/ice-servers.json` file.
|
2021-01-19 18:04:39 +01:00
|
|
|
|
|
|
|
|
|
Some users may prefer to use an external ICE server. In that case, the
|
2021-05-10 23:24:18 +02:00
|
|
|
|
built-in TURN server should be disabled (`-turn ""` or the default
|
|
|
|
|
`-turn auto`), and a working ICE configuration should be given in the file
|
2021-01-19 18:04:39 +01:00
|
|
|
|
`data/ice-servers.json`. In the case of a single STUN server, it should
|
|
|
|
|
look like this:
|
2021-01-18 20:24:52 +01:00
|
|
|
|
|
|
|
|
|
[
|
|
|
|
|
{
|
|
|
|
|
"urls": [
|
|
|
|
|
"stun:stun.example.org"
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
In the case of s single TURN server, the `ice-servers.json` file should
|
|
|
|
|
look like this:
|
|
|
|
|
|
|
|
|
|
[
|
|
|
|
|
{
|
|
|
|
|
"urls": [
|
|
|
|
|
"turn:turn.example.org:443",
|
|
|
|
|
"turn:turn.example.org:443?transport=tcp"
|
|
|
|
|
],
|
|
|
|
|
"username": "galene",
|
|
|
|
|
"credential": "secret"
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
|
2021-01-19 18:04:39 +01:00
|
|
|
|
If you prefer to use coturn's `use-auth-secret` option, then the
|
|
|
|
|
`ice-servers.json` file should look like this:
|
2021-01-18 20:24:52 +01:00
|
|
|
|
|
|
|
|
|
[
|
|
|
|
|
{
|
2021-07-04 15:07:12 +02:00
|
|
|
|
"urls": [
|
2021-01-18 20:24:52 +01:00
|
|
|
|
"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. If an `ice-servers.json` file is present and
|
|
|
|
|
Galène's built-in TURN server is enabled, then the external server will be
|
|
|
|
|
used in preference to the built-in server.
|
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-24 16:57:26 +01:00
|
|
|
|
# Further information
|
|
|
|
|
|
|
|
|
|
Galène's web page is at <https://galene.org>.
|
|
|
|
|
|
|
|
|
|
Answers to common questions and issues are at <https://galene.org#faq>.
|
|
|
|
|
|
2021-05-10 23:24:18 +02:00
|
|
|
|
|
2021-01-18 20:24:52 +01:00
|
|
|
|
-- Juliusz Chroboczek <https://www.irif.fr/~jch/>
|