1
Fork 0
mirror of https://github.com/jech/galene.git synced 2024-11-22 08:35:57 +01:00

Update README.

This commit is contained in:
Juliusz Chroboczek 2021-01-08 15:36:23 +01:00
parent 2ad9e9d2b1
commit 50a3d8b855

203
README
View file

@ -15,20 +15,64 @@ This step is optional.
echo 'god:topsecret' > data/passwd echo 'god:topsecret' > data/passwd
## Set up a TURN server ## Set up an ICE server
This step depends on your network setup and your user population. If your ICE is the NAT and firewall traversal protocol used by WebRTC. ICE uses
server is accessible from the Internet (no firewall or NAT) and none of a variety of techniques for establishing a flow in the presence of
your users are behind restrictive firewalls, then no ICE servers are a firewall; the two most effective techniques, STUN and TURN, require help
necessary. If your server is behind a NAT, a STUN server is required. If from an external server. Whether you need a helping server depends both
any of your users are behind restrictive firewalls (which is usually the on your firewalling setup and on the networks of your users; for
case of Academic and Enterprise networks), then you will need a TURN production use, you should probably use your own TURN server.
server running on an innocent-looking TCP port. This is the recommended
setup.
You should probably be running your own TURN server. The address of the ### No ICE server
TURN server is configured in the file `data/ice-servers.json`. It should
look like this: 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:
[ [
{ {
@ -37,37 +81,60 @@ look like this:
"turn:turn.example.com:443?transport=tcp" "turn:turn.example.com:443?transport=tcp"
], ],
"username": "galene", "username": "galene",
"credential": "secret" "credential": "secret",
"credentialType": "hmac-sha1"
} }
] ]
If you use coturn's `use-auth-secret` option, set `credentialType` to For redundancy, you may set up multiple TURN servers, and ICE will use the
`hmac-sha1`. first one that works.
## Set up a group ## Set up a group
A group is set up by creating a file `groups/name.json`. The available A group is set up by creating a file `groups/name.json`.
options are described below.
mkdir groups mkdir groups
vi groups/public.json vi groups/groupname.json
A group with a single operator and no password for ordinary users looks
like this:
{ {
"public": true, "op": [{"username": "jch", "password": "1234"}],
"op": [{"username":"jch", "password":"1234"}], "presenter": [{}]
"presenter": [{}],
"max-users": 100
} }
A group with one operator and two users looks like this:
## Copy the necessary files to your server: {
"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.
Assuming you have set up a user *galene*: ## Test locally
./galene &
You should be able to access Galène at `https://localhost:8443`.
## Deploy to your server
Set up a user *galene* on your server, then do:
rsync -a galene static data groups galene@server.example.org: rsync -a galene static data groups galene@server.example.org:
## Run the server binary: Now run the binary on the server:
ssh galene@server.example.org ssh galene@server.example.org
ulimit -n 65536
nohup ./galene & nohup ./galene &
If you are using *runit*, use a script like the following: If you are using *runit*, use a script like the following:
@ -78,7 +145,7 @@ If you are using *runit*, use a script like the following:
ulimit -n 65536 ulimit -n 65536
exec setuidgid galene ./galene exec setuidgid galene ./galene
If you are using *systemd*, something like this should do: If you are using *systemd*:
[Unit] [Unit]
Description=Galene Description=Galene
@ -95,7 +162,9 @@ If you are using *systemd*, something like this should do:
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target
# Locations # Usage
## Locations
There is a landing page at the root of the server. It contains a form 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. for typing the name of a group, and a clickable list of public groups.
@ -109,15 +178,33 @@ available to the administrator of the group.
Some statistics are available under `/stats`. This is only available to Some statistics are available under `/stats`. This is only available to
the server administrator. the server administrator.
## Side menu
# Group definitions 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.
Groups are defined by files in the directory defined by the `-groups` ## Commands
command-line option, one per group. The group definition file does not
contain the name of the group -- that makes it possible to set up a new
group just by copying a template file.
The group definition file contains a JSON directory with the following 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 fields. All fields are optional, but unless you specify at least one user
definition (`op`, `presenter`, or `other`), nobody will be able to join definition (`op`, `presenter`, or `other`), nobody will be able to join
the group. the group.
@ -134,16 +221,24 @@ the group.
- `max-history-age`: the time, in seconds, during which chat history is - `max-history-age`: the time, in seconds, during which chat history is
kept (default 14400, i.e. 4 hours); kept (default 14400, i.e. 4 hours);
- `allow-recording`: if true, then recording is allowed in this group; - `allow-recording`: if true, then recording is allowed in this group;
- `allow-anonymous`: if true, then users may connect with an empty username. - `allow-anonymous`: if true, then users may connect with an empty username;
- `allow-subgroups`: if true, then subgroups of the form `group/subgroup` - `allow-subgroups`: if true, then subgroups of the form `group/subgroup`
are automatically created when accessed. are automatically created when first accessed;
- `redirect`: if set, then attempts to join the group will be redirected - `redirect`: if set, then attempts to join the group will be redirected
to the given URL; most other fields are ignored in this case. 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 - `codecs`: this is a list of codecs allowed in this group. The default
is `["vp8", "opus"]`. Other possible values include `"vp9"` is `["vp8", "opus"]`.
(incompatible with Mac OS), `"h264"` (incompatible with some versions
of Firefox and Chromium), `"g722"`, `"pcmu"` and `"pcma"`. Recording Supported video codecs include:
to disk is only supported for `"vp8"` and `"opus"`.
- `"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: A user definition is a dictionary with the following fields:
@ -155,14 +250,21 @@ A user definition is a dictionary with the following fields:
For example, For example,
{"username": "jch", "password": "topsecret"} {"username": "jch", "password": "1234"}
specifies user *jch* with password *topsecret*, while specifies user *jch* with password *1234*, while
{"password": "topsecret"} {"password": "1234"}
specifies that any username will do. An entry with a hashed password specifies that any (non-empty) username will do, and
looks like this:
{}
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", "username": "jch",
@ -175,11 +277,4 @@ looks like this:
} }
} }
# 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.
--- Juliusz Chroboczek <https://www.irif.fr/~jch/> --- Juliusz Chroboczek <https://www.irif.fr/~jch/>