Update man page

1 files changed, 265 insertions, 48 deletions

diff --git a/man/ejabberd.yml.5 b/man/ejabberd.yml.5
index 48c4509f4..82c9340cc 100644
--- a/man/ejabberd.yml.5
+++ b/man/ejabberd.yml.5
@@ -1,13 +1,13 @@
 '\" t
 .\"     Title: ejabberd.yml
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 12/08/2021
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 05/04/2022
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "EJABBERD\&.YML" "5" "12/08/2021" "\ \&" "\ \&"
+.TH "EJABBERD\&.YML" "5" "05/04/2022" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -82,7 +82,7 @@ All options can be changed in runtime by running \fIejabberdctl reload\-config\f
 .sp
 Some options can be specified for particular virtual host(s) only using \fIhost_config\fR or \fIappend_host_config\fR options\&. Such options are called \fIlocal\fR\&. Examples are \fImodules\fR, \fIauth_method\fR and \fIdefault_db\fR\&. The options that cannot be defined per virtual host are called \fIglobal\fR\&. Examples are \fIloglevel\fR, \fIcertfiles\fR and \fIlisten\fR\&. It is a configuration mistake to put \fIglobal\fR options under \fIhost_config\fR or \fIappend_host_config\fR section \- ejabberd will refuse to load such configuration\&.
 .sp
-It is not recommended to write ejabberd\&.yml from scratch\&. Instead it is better to start from "default" configuration file available at https://github\&.com/processone/ejabberd/blob/21\&.12/ejabberd\&.yml\&.example\&. Once you get ejabberd running you can start changing configuration options to meet your requirements\&.
+It is not recommended to write ejabberd\&.yml from scratch\&. Instead it is better to start from "default" configuration file available at https://github\&.com/processone/ejabberd/blob/22\&.05/ejabberd\&.yml\&.example\&. Once you get ejabberd running you can start changing configuration options to meet your requirements\&.
 .sp
 Note that this document is intended to provide comprehensive description of all configuration options that can be consulted to understand the meaning of a particular option, its format and possible values\&. It will be quite hard to understand how to configure ejabberd by reading this document only \- for this purpose the reader is recommended to read online Configuration Guide available at https://docs\&.ejabberd\&.im/admin/configuration\&.
 .SH "TOP LEVEL OPTIONS"
@@ -91,7 +91,8 @@ This section describes top level options of ejabberd\&.
 .PP
 \fBaccess_rules\fR: \fI{AccessName: {allow|deny: ACLRules|ACLName}}\fR
 .RS 4
-The option specifies access rules\&. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from
+This option defines
+Access Rules\&. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from
 \fIaccess\fR
 options of ejabberd modules)\&. Each rule definition may contain arbitrary number of
 \fIallow\fR
@@ -1062,7 +1063,7 @@ This option can be used to tune tick time parameter of
 Whether to use
 \fInew\fR
 SQL schema\&. All schemas are located at
-https://github\&.com/processone/ejabberd/tree/21\&.12/sql\&. There are two schemas available\&. The default legacy schema allows to store one XMPP domain into one ejabberd database\&. The
+https://github\&.com/processone/ejabberd/tree/22\&.05/sql\&. There are two schemas available\&. The default legacy schema allows to store one XMPP domain into one ejabberd database\&. The
 \fInew\fR
 schema allows to handle several XMPP domains in a single ejabberd database\&. Using this
 \fInew\fR
@@ -1360,9 +1361,10 @@ seconds\&.
 .PP
 \fBs2s_access\fR: \fIAccess\fR
 .RS 4
-The access rule to restrict server\-to\-server connections\&. The default value is
-\fIall\fR
-which means no restrictions are applied\&.
+This
+Access Rule
+defines to what remote servers can s2s connections be established\&. The default value is
+\fIall\fR; no restrictions are applied, it is allowed to connect s2s to/from all remote servers\&.
 .RE
 .PP
 \fBs2s_cafile\fR: \fIPath\fR
@@ -1776,7 +1778,7 @@ module\&. The default value is obtained at compile time from the underlying vers
 .RS 4
 This option enables validation for
 \fIOrigin\fR
-header to protect against connections from other domains than given in the configuration file\&. In this way, the lower layer load balancer can be chosen for a specific ejabberd implementation while still providing a secure Websocket connection\&. The default value is
+header to protect against connections from other domains than given in the configuration file\&. In this way, the lower layer load balancer can be chosen for a specific ejabberd implementation while still providing a secure WebSocket connection\&. The default value is
 \fIignore\fR\&. An example value of the
 \fIURL\fR
 is "https://test\&.example\&.org:8081"\&.
@@ -1784,7 +1786,7 @@ is "https://test\&.example\&.org:8081"\&.
 .PP
 \fBwebsocket_ping_interval\fR: \fItimeout()\fR
 .RS 4
-Defines time between pings sent by the server to a client (Websocket level protocol pings are used for this) to keep a connection active\&. If the client doesn\(cqt respond to two consecutive pings, the connection will be assumed as closed\&. The value of
+Defines time between pings sent by the server to a client (WebSocket level protocol pings are used for this) to keep a connection active\&. If the client doesn\(cqt respond to two consecutive pings, the connection will be assumed as closed\&. The value of
 \fI0\fR
 can be used to disable the feature\&. This option makes the server sending pings only for connections using the RFC compliant protocol\&. For older style connections the server expects that whitespace pings would be used for this purpose\&. The default value is
 \fI60\fR
@@ -2164,7 +2166,7 @@ This module depends on \fImod_privacy\fR where all the configuration is performe
 The module has no options\&.
 .SS "mod_bosh"
 .sp
-This module implements XMPP over BOSH as defined in XEP\-0124 and XEP\-0206\&. BOSH stands for Bidirectional\-streams Over Synchronous HTTP\&. It makes it possible to simulate long lived connections required by XMPP over the HTTP protocol\&. In practice, this module makes it possible to use XMPP in a browser without Websocket support and more generally to have a way to use XMPP while having to get through an HTTP proxy\&.
+This module implements XMPP over BOSH as defined in XEP\-0124 and XEP\-0206\&. BOSH stands for Bidirectional\-streams Over Synchronous HTTP\&. It makes it possible to simulate long lived connections required by XMPP over the HTTP protocol\&. In practice, this module makes it possible to use XMPP in a browser without WebSocket support and more generally to have a way to use XMPP while having to get through an HTTP proxy\&.
 .sp
 .it 1 an-trap
 .nr an-no-space-flag 1
@@ -2234,9 +2236,9 @@ option, but applied to this module only\&.
 .PP
 \fBram_db_type\fR: \fImnesia | sql | redis\fR
 .RS 4
-Same as
+Same as top\-level
 \fIdefault_ram_db\fR
-but applied to this module only\&.
+option, but applied to this module only\&.
 .RE
 .PP
 \fBuse_cache\fR: \fItrue | false\fR
@@ -2370,11 +2372,13 @@ The module has no options\&.
 .sp
 This module serves a simple page for the Converse XMPP web browser client\&.
 .sp
+This module is available since ejabberd 21\&.12\&. Several options were improved in ejabberd 22\&.05\&.
+.sp
 To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR → \fIejabberd_http\fR → request_handlers\&.
 .sp
-You must also setup either the option \fIwebsocket_url\fR or \fIbosh_service_url\fR\&.
+Make sure either \fImod_bosh\fR or \fIejabberd_http_ws\fR request_handlers are enabled\&.
 .sp
-By default, the options \fIconversejs_css\fR and \fIconversejs_script\fR point to the public Converse\&.js client\&. Alternatively, you can host the client locally using \fImod_http_fileserver\fR\&.
+When \fIconversejs_css\fR and \fIconversejs_script\fR are \fIauto\fR, by default they point to the public Converse client\&.
 .sp
 .it 1 an-trap
 .nr an-no-space-flag 1
@@ -2384,29 +2388,61 @@ By default, the options \fIconversejs_css\fR and \fIconversejs_script\fR point t
 \fBAvailable options:\fR
 .RS 4
 .PP
-\fBbosh_service_url\fR: \fIBoshURL\fR
+\fBbosh_service_url\fR: \fIauto | BoshURL\fR
 .RS 4
-BOSH service URL to which Converse\&.js can connect to\&.
+BOSH service URL to which Converse can connect to\&. The keyword
+\fI@HOST@\fR
+is replaced with the real virtual host name\&. If set to
+\fIauto\fR, it will build the URL of the first configured BOSH request handler\&. The default value is
+\fIauto\fR\&.
 .RE
 .PP
-\fBconversejs_css\fR: \fIURL\fR
+\fBconversejs_css\fR: \fIauto | URL\fR
 .RS 4
-Converse\&.js CSS URL\&.
+Converse CSS URL\&. The keyword
+\fI@HOST@\fR
+is replaced with the hostname\&. The default value is
+\fIauto\fR\&.
 .RE
+.sp
+\fINote\fR about the next option: added in 22\&.05:
 .PP
-\fBconversejs_script\fR: \fIURL\fR
+\fBconversejs_options\fR: \fI{Name: Value}\fR
 .RS 4
-Converse\&.js main script URL\&.
+Specify additional options to be passed to Converse\&. See
+Converse configuration\&. Only boolean, integer and string values are supported; lists are not supported\&.
+.RE
+.sp
+\fINote\fR about the next option: added in 22\&.05:
+.PP
+\fBconversejs_resources\fR: \fIPath\fR
+.RS 4
+Local path to the Converse files\&. If not set, the public Converse client will be used instead\&.
+.RE
+.PP
+\fBconversejs_script\fR: \fIauto | URL\fR
+.RS 4
+Converse main script URL\&. The keyword
+\fI@HOST@\fR
+is replaced with the hostname\&. The default value is
+\fIauto\fR\&.
 .RE
 .PP
 \fBdefault_domain\fR: \fIDomain\fR
 .RS 4
-Specify a domain to act as the default for user JIDs\&. The default value is the first domain defined in the ejabberd configuration file\&.
+Specify a domain to act as the default for user JIDs\&. The keyword
+\fI@HOST@\fR
+is replaced with the hostname\&. The default value is
+\fI@HOST@\fR\&.
 .RE
 .PP
-\fBwebsocket_url\fR: \fIWebsocketURL\fR
+\fBwebsocket_url\fR: \fIauto | WebSocketURL\fR
 .RS 4
-A websocket URL to which Converse\&.js can connect to\&.
+A WebSocket URL to which Converse can connect to\&. The keyword
+\fI@HOST@\fR
+is replaced with the real virtual host name\&. If set to
+\fIauto\fR, it will build the URL of the first configured WebSocket request handler\&. The default value is
+\fIauto\fR\&.
 .RE
 .RE
 .sp
@@ -2415,9 +2451,11 @@ A websocket URL to which Converse\&.js can connect to\&.
 .nr an-break-flag 1
 .br
 .ps +1
-\fBExample:\fR
+\fBExamples:\fR
 .RS 4
 .sp
+Manually setup WebSocket url, and use the public Converse client:
+.sp
 .if n \{\
 .RS 4
 .\}
@@ -2427,12 +2465,58 @@ listen:
     port: 5280
     module: ejabberd_http
     request_handlers:
+      /bosh: mod_bosh
       /websocket: ejabberd_http_ws
       /conversejs: mod_conversejs
 
 modules:
+  mod_bosh: {}
   mod_conversejs:
-    websocket_url: "ws://example\&.org:5280/websocket"
+    websocket_url: "ws://@HOST@:5280/websocket"
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Host Converse locally and let auto detection of WebSocket and Converse URLs:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+listen:
+  \-
+    port: 443
+    module: ejabberd_http
+    tls: true
+    request_handlers:
+      /websocket: ejabberd_http_ws
+      /conversejs: mod_conversejs
+
+modules:
+  mod_conversejs:
+    conversejs_resources: "/home/ejabberd/conversejs\-9\&.0\&.0/package/dist"
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Configure some additional options for Converse
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+modules:
+  mod_conversejs:
+    websocket_url: auto
+    conversejs_options:
+      auto_away: 30
+      clear_cache_on_logout: true
+      i18n: "pt"
+      locked_domain: "@HOST@"
+      message_archiving: always
+      theme: dracula
 .fi
 .if n \{\
 .RE
@@ -2676,9 +2760,79 @@ The number of C2S authentication failures to trigger the IP ban\&. The default v
 \fI20\fR\&.
 .RE
 .RE
+.SS "mod_host_meta"
+.sp
+This module serves small \fIhost\-meta\fR files as described in XEP\-0156: Discovering Alternative XMPP Connection Methods\&.
+.sp
+This module is available since ejabberd 22\&.05\&.
+.sp
+To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR → \fIejabberd_http\fR → request_handlers\&.
+.sp
+Notice it only works if ejabberd_http has tls enabled\&.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBAvailable options:\fR
+.RS 4
+.PP
+\fBbosh_service_url\fR: \fIundefined | auto | BoshURL\fR
+.RS 4
+BOSH service URL to announce\&. The keyword
+\fI@HOST@\fR
+is replaced with the real virtual host name\&. If set to
+\fIauto\fR, it will build the URL of the first configured BOSH request handler\&. The default value is
+\fIauto\fR\&.
+.RE
+.PP
+\fBwebsocket_url\fR: \fIundefined | auto | WebSocketURL\fR
+.RS 4
+WebSocket URL to announce\&. The keyword
+\fI@HOST@\fR
+is replaced with the real virtual host name\&. If set to
+\fIauto\fR, it will build the URL of the first configured WebSocket request handler\&. The default value is
+\fIauto\fR\&.
+.RE
+.RE
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBExample:\fR
+.RS 4
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+listen:
+  \-
+    port: 443
+    module: ejabberd_http
+    tls: true
+    request_handlers:
+      /bosh: mod_bosh
+      /ws: ejabberd_http_ws
+      /\&.well\-known/host\-meta: mod_host_meta
+      /\&.well\-known/host\-meta\&.json: mod_host_meta
+
+modules:
+  mod_bosh: {}
+  mod_host_meta:
+    bosh_service_url: "https://@HOST@:5443/bosh"
+    websocket_url: "wss://@HOST@:5443/ws"
+.fi
+.if n \{\
+.RE
+.\}
+.RE
 .SS "mod_http_api"
 .sp
-This module provides a ReST API to call ejabberd commands using JSON data\&.
+This module provides a ReST interface to call ejabberd API commands using JSON data\&.
 .sp
 To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR → \fIejabberd_http\fR → request_handlers\&.
 .sp
@@ -3702,14 +3856,23 @@ This option specifies who is allowed to register nickname within the Multi\-User
 \fIall\fR
 for backward compatibility, which means that any user is allowed to register any free nick\&.
 .RE
+.sp
+\fINote\fR about the next option: added in 22\&.05:
+.PP
+\fBcleanup_affiliations_on_start\fR: \fItrue | false\fR
+.RS 4
+Remove affiliations for non\-existing local users on startup\&. The default value is
+\fIfalse\fR\&.
+.RE
 .PP
 \fBdb_type\fR: \fImnesia | sql\fR
 .RS 4
-Define the type of persistent storage where the module will store room information\&. The default is the storage defined by the global option
-\fIdefault_db\fR, or
-\fImnesia\fR
-if omitted\&.
+Same as top\-level
+\fIdefault_db\fR
+option, but applied to this module only\&.
 .RE
+.sp
+\fINote\fR about the next option: improved in 22\&.05:
 .PP
 \fBdefault_room_options\fR: \fIOptions\fR
 .RS 4
@@ -3767,6 +3930,12 @@ Allow visitors to send status text in presence updates\&. If disallowed, the sta
 \fItrue\fR\&.
 .RE
 .PP
+\fBallow_voice_requests\fR: \fItrue | false\fR
+.RS 4
+Allow visitors in a moderated room to request voice\&. The default value is
+\fItrue\fR\&.
+.RE
+.PP
 \fBanonymous\fR: \fItrue | false\fR
 .RS 4
 The room is anonymous: occupants don\(cqt see the real JIDs of other occupants\&. Note that the room moderators can always see the real JIDs of the occupants\&. The default value is
@@ -3781,6 +3950,17 @@ in order to accept their join in the room\&. The default value is
 \fIfalse\fR\&.
 .RE
 .PP
+\fBdescription\fR: \fIRoom Description\fR
+.RS 4
+Short description of the room\&. The default value is an empty string\&.
+.RE
+.PP
+\fBenable_hats\fR: \fItrue | false\fR
+.RS 4
+Allow extended roles as defined in XEP\-0317 Hats\&. The default value is
+\fIfalse\fR\&.
+.RE
+.PP
 \fBlang\fR: \fILanguage\fR
 .RS 4
 Preferred language for the discussions in the room\&. The language format should conform to RFC 5646\&. There is no value by default\&.
@@ -3878,10 +4058,26 @@ The list of participants is public, without requiring to enter the room\&. The d
 \fItrue\fR\&.
 .RE
 .PP
+\fBpubsub\fR: \fIPubSub Node\fR
+.RS 4
+XMPP URI of associated Publish/Subscribe node\&. The default value is an empty string\&.
+.RE
+.PP
 \fBtitle\fR: \fIRoom Title\fR
 .RS 4
 A human\-readable title of the room\&. There is no default value
 .RE
+.PP
+\fBvcard\fR: \fIvCard\fR
+.RS 4
+A custom vCard for the room\&. See the equivalent mod_muc option\&.The default value is an empty string\&.
+.RE
+.PP
+\fBvoice_request_min_interval\fR: \fINumber\fR
+.RS 4
+Minimum interval between voice requests, in seconds\&. The default value is
+\fI1800\fR\&.
+.RE
 .RE
 .PP
 \fBhibernation_timeout\fR: \fIinfinity | Seconds\fR
@@ -4010,9 +4206,9 @@ option, but applied to this module only\&.
 .PP
 \fBram_db_type\fR: \fImnesia | sql\fR
 .RS 4
-Define the type of volatile (in\-memory) storage where the module will store room information (\fImuc_online_room\fR
-and
-\fImuc_online_users\fR)\&.
+Same as top\-level
+\fIdefault_ram_db\fR
+option, but applied to this module only\&.
 .RE
 .PP
 \fBregexp_room_id\fR: \fIstring()\fR
@@ -4086,7 +4282,24 @@ This module provides commands to administer local MUC services and their MUC roo
 .sp
 This module depends on \fImod_muc\fR\&.
 .sp
-The module has no options\&.
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBAvailable options:\fR
+.RS 4
+.sp
+\fINote\fR about the next option: added in 22\&.05:
+.PP
+\fBsubscribe_room_many_max_users\fR: \fINumber\fR
+.RS 4
+How many users can be subscribed to a room at once using the
+\fIsubscribe_room_many\fR
+command\&. The default value is
+\fI50\fR\&.
+.RE
+.RE
 .SS "mod_muc_log"
 .sp
 This module enables optional logging of Multi\-User Chat (MUC) public conversations to HTML\&. Once you enable this module, users can join a room using a MUC capable XMPP client, and if they have enough privileges, they can request the configuration form in which they can set the option to enable room logging\&.
@@ -4585,11 +4798,13 @@ option, but applied to this module only\&.
 .PP
 \fBuse_mam_for_storage\fR: \fItrue | false\fR
 .RS 4
-This is an experimental option\&. Enabling this option will make
+This is an experimental option\&. Enabling this option,
 \fImod_offline\fR
-not use the former spool table for storing MucSub offline messages, but will use the archive table instead\&. This use of the archive table is cleaner and it makes it possible for clients to slowly drop the former offline use case and rely on message archive instead\&. It also further reduces the storage required when you enabled MucSub\&. Enabling this option has a known drawback for the moment: most of flexible message retrieval queries don\(cqt work (those that allow retrieval/deletion of messages by id), but this specification is not widely used\&. The default value is
+uses the
+\fImod_mam\fR
+archive table instead of its own spool table to retrieve the messages received when the user was offline\&. This allows client developers to slowly drop XEP\-0160 and rely on XEP\-0313 instead\&. It also further reduces the storage required when you enable MucSub\&. Enabling this option has a known drawback for the moment: most of flexible message retrieval queries don\(cqt work (those that allow retrieval/deletion of messages by id), but this specification is not widely used\&. The default value is
 \fIfalse\fR
-to keep former behaviour as default and ensure this option is disabled\&.
+to keep former behaviour as default\&.
 .RE
 .RE
 .sp
@@ -5085,7 +5300,9 @@ A port number to listen for incoming connections\&. The default value is
 .PP
 \fBram_db_type\fR: \fImnesia | redis | sql\fR
 .RS 4
-Define the type of volatile (in\-memory) storage where the module will store room information\&.
+Same as top\-level
+\fIdefault_ram_db\fR
+option, but applied to this module only\&.
 .RE
 .PP
 \fBrecbuf\fR: \fISize\fR
@@ -5284,6 +5501,8 @@ To specify whether or not pubsub should cache last items\&. Value is
 or
 \fIfalse\fR\&. If not defined, pubsub does not cache last items\&. On systems with not so many nodes, caching last items speeds up pubsub and allows to raise user connection rate\&. The cost is memory usage, as every item is stored in memory\&.
 .RE
+.sp
+\fINote\fR about the next option: added in 21\&.12:
 .PP
 \fBmax_item_expire_node\fR: \fItimeout() | infinity\fR
 .RS 4
@@ -5682,6 +5901,8 @@ doesn\(cqt allow to register new accounts from s2s or existing c2s sessions\&. Y
 .RS 4
 Specify rules to restrict access for user unregistration\&. By default any user is able to unregister their account\&.
 .RE
+.sp
+\fINote\fR about the next option: added in 21\&.12:
 .PP
 \fBallow_modules\fR: \fIall | [Module, \&.\&.\&.]\fR
 .RS 4
@@ -6100,13 +6321,9 @@ option, but applied to this module only\&.
 .PP
 \fBdb_type\fR: \fImnesia | sql\fR
 .RS 4
-Define the type of storage where the module will create the tables and store user information\&. The default is the storage defined by the top\-level
+Same as top\-level
 \fIdefault_db\fR
-option, or
-\fImnesia\fR
-if omitted\&. If
-\fIsql\fR
-value is defined, make sure you have defined the database\&.
+option, but applied to this module only\&.
 .RE
 .PP
 \fBuse_cache\fR: \fItrue | false\fR
@@ -7380,13 +7597,13 @@ TODO
 ProcessOne\&.
 .SH "VERSION"
 .sp
-This document describes the configuration file of ejabberd 21\&.12\&. Configuration options of other ejabberd versions may differ significantly\&.
+This document describes the configuration file of ejabberd 22\&.05\&. Configuration options of other ejabberd versions may differ significantly\&.
 .SH "REPORTING BUGS"
 .sp
 Report bugs to https://github\&.com/processone/ejabberd/issues
 .SH "SEE ALSO"
 .sp
-Default configuration file: https://github\&.com/processone/ejabberd/blob/21\&.12/ejabberd\&.yml\&.example
+Default configuration file: https://github\&.com/processone/ejabberd/blob/22\&.05/ejabberd\&.yml\&.example
 .sp
 Main site: https://ejabberd\&.im
 .sp