From 976df35e81b4e2a74fa31e5d0f7f269edeb0c2c4 Mon Sep 17 00:00:00 2001
From: Juliusz Chroboczek <jch@irif.fr>
Date: Tue, 4 Apr 2023 23:05:52 +0200
Subject: [PATCH] Update README.

---
 README | 72 ++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 55 insertions(+), 17 deletions(-)

diff --git a/README b/README
index b82bb60..587cd23 100644
--- a/README
+++ b/README
@@ -14,17 +14,29 @@ See the file INSTALL in this directory for installation instructions.
 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
+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
+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
+## Main interface
+
+After logging in, the user is confronted with the main interface.
+
+### Buttons
+
+There are up to three buttons at the top.  The *Enable*/*Disable* button
+enables either or both the camera and the microphone (depending on the
+options set in the side menu, see below).  The *Mute* button mutes or
+unmutes the microphone.  The *Share Screen* button shares the screen or
+a window.
+
+### 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
@@ -32,13 +44,20 @@ the camera and microphone and setting the video throughput.  The
 in favour of image quality.  The *Play local file* dialog allows streaming
 a video from a local file.
 
+### User list
 
-## Commands
+There is a user list on the left.  Clicking on a user opens a menu with
+actions that can be applied to that user.  Clicking on ones own username
+opens a menu with actions that are global to the group.
 
-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.
+### Text box
+
+Typing a string in the text box at the bottom of the chat pane sends
+a broadcast message to all of the users in the group.
+
+Typing a line starting with a slash `/` in the text box 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
@@ -53,10 +72,10 @@ file may look as follows:
 
 The fields are as follows:
 
-- `proxyURL`: if running behind a reverse proxy, this specifies the
-  address of the proxy.
 - `admin` defines the users allowed to look at the `/stats.html` file; it
   has the same syntax as user definitions in groups (see below).
+- `proxyURL`: if running behind a reverse proxy, this specifies the
+  address of the proxy.
 - `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.
@@ -142,13 +161,13 @@ 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).
+Galene implements three authorisation methods: a simple username/password
+authorisation scheme, a scheme using stateful tokens and a mechanism based
+on cryptographic tokens that are generated by an external server.  The
+former two mechanism are 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
 
@@ -198,6 +217,25 @@ user entry with a hashed password looks like this:
         }
     }
 
+### Stateful tokens
+
+Stateful tokens allow to temporarily grant access to a user.  In order to
+generate a stateful token, the group administrator types
+
+    /invite user period
+
+where `user` is the username granted to the temporary user, and `period`
+is the time period for which the token will be valid (for example `2d`
+meaning 2 days).  The server replies with a link, valid the given time
+period, that may be sent to the temporary user for example by e-mail.
+
+Tokens may also be granted without imposing a specific username:
+
+    /invite '' 2d
+
+Stateful tokens are revokable (use the `/revoke` command) and their
+lifetime may be extended (use the `/reinvite` command).
+
 
 ### Authorisation servers