Logically, configuration options are split into 3 main categories: \fIModules\fR, \fIListeners\fR and everything else called \fITop Level\fR options\&. Thus this document is split into 3 main chapters describing each category separately\&. So, the contents of ejabberd\&.yml will typically look like this:
Any configuration error (such as syntax error, unknown option or invalid option value) is fatal in the sense that ejabberd will refuse to load the whole configuration file and will not start or will abort configuration reload\&.
.sp
All options can be changed in runtime by running \fIejabberdctl reload\-config\fR command\&. Configuration reload is atomic: either all options are accepted and applied simultaneously or the new configuration is refused without any impact on currently running configuration\&.
.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\&.
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/24\&.12/ejabberd\&.yml\&.example\&. Once you get ejabberd running you can start changing configuration options to meet your requirements\&.
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\&.
\fIbasic\&.md#access\-rules|Access Rules\fR\&. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from
\fI\&.\&./configuration/basic\&.md#acl|access control lists\fR: named sets of rules which are used to match against different targets (such as a JID or an IP address)\&. Every set of rules has name
The rule matches any JID with node part matching regular expression
\fIuser_regexp\fR
and server part matching regular expression
\fIserver_regexp\fR\&.
.RE
.PP
\fBresource\fR: \fIResource\fR
.RS4
The rule matches any JID with a resource
\fIResource\fR\&.
.RE
.PP
\fBresource_glob\fR: \fIPattern\fR
.RS4
Same as
\fIresource_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBresource_regexp\fR: \fIRegexp\fR
.RS4
The rule matches any JID with a resource that matches regular expression
\fIRegexp\fR\&.
.RE
.PP
\fBserver\fR: \fIServer\fR
.RS4
The rule matches any JID from server
\fIServer\fR\&. The value of
\fIServer\fR
must be a valid hostname or an IP address\&.
.RE
.PP
\fBserver_glob\fR: \fIPattern\fR
.RS4
Same as
\fIserver_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBserver_regexp\fR: \fIRegexp\fR
.RS4
The rule matches any JID from the server that matches regular expression
\fIRegexp\fR\&.
.RE
.PP
\fBuser\fR: \fIUsername\fR
.RS4
If
\fIUsername\fR
is in the form of "user@server", the rule matches a JID against this value\&. Otherwise, if
\fIUsername\fR
is in the form of "user", the rule matches any JID that has
\fIUsername\fR
in the node part as long as the server part of this JID is any virtual host served by ejabberd\&.
.RE
.PP
\fBuser_glob\fR: \fIPattern\fR
.RS4
Same as
\fIuser_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBuser_regexp\fR: \fIRegexp\fR
.RS4
If
\fIRegexp\fR
is in the form of "regexp@server", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is equal to "server"\&. If
\fIRegexp\fR
is in the form of "regexp", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is any virtual host served by ejabberd\&.
configuration, to automatically obtain SSL certificates for the domains served by ejabberd, which means that certificate requests and renewals are performed to some CA server (aka "ACME server") in a fully automated mode\&. The
Whether to automatically request certificates for all configured domains (that yet have no a certificate) on server start or configuration reload\&. The default is
\fItrue\fR\&.
.RE
.PP
\fBca_url\fR: \fIURL\fR
.RS4
The ACME directory URL used as an entry point for the ACME server\&. The default value is
\- the directory URL of Let\(cqs Encrypt authority\&.
.RE
.PP
\fBcert_type\fR: \fIrsa | ec\fR
.RS4
A type of a certificate key\&. Available values are
\fIec\fR
and
\fIrsa\fR
for EC and RSA certificates respectively\&. It\(cqs better to have RSA certificates for the purpose of backward compatibility with legacy clients and servers, thus the default is
\fIrsa\fR\&.
.RE
.PP
\fBcontact\fR: \fI[Contact, \&.\&.\&.]\fR
.RS4
A list of contact addresses (typically emails) where an ACME server will send notifications when problems occur\&. The value of
\fIContact\fR
must be in the form of "scheme:address" (e\&.g\&. "mailto:user@domain\&.tld")\&. The default is an empty list which means an ACME server will send no notices\&.
This option is only used when the anonymous mode is enabled\&. Setting it to
\fItrue\fR
means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect\&. This option is only useful in very special occasions\&. The default value is
methods to use\&. If several methods are defined, authentication is considered successful as long as authentication of at least one of the methods succeeds\&. The default value is
\fIplain\fR: The password is stored as plain text in the database\&. This is risky because the passwords can be read if your database gets compromised\&. This is the default value\&. This format allows clients to authenticate using: the old Jabber Non\-SASL (XEP\-0078), SASL PLAIN, SASL DIGEST\-MD5, and SASL SCRAM\-SHA\-1/256/512(\-PLUS)\&.
\fIscram\fR: The password is not stored, only some information required to verify the hash provided by the client\&. It is impossible to obtain the original plain password from the stored information; for this reason, when this value is configured it cannot be changed to plain anymore\&. This format allows clients to authenticate using: SASL PLAIN and SASL SCRAM\-SHA\-1/256/512(\-PLUS)\&. The SCRAM variant depends on the
format\&. You shouldn\(cqt change this if you already have passwords generated with a different algorithm \- users that have such passwords will not be able to authenticate\&. The default value is
Full path to a file containing one or more CA certificates in PEM format\&. All client certificates should be signed by one of these root CA certificates and should contain the corresponding JID(s) in
To set a specific file per listener, use the listener\(cqs \fIlisten\-options\&.md#cafile|cafile\fR option\&. Please notice that \fIc2s_cafile\fR overrides the listener\(cqs \fIcafile\fR option\&.
Full path to a file containing custom DH parameters to use for c2s connections\&. Such a file could be created with the command
\fI"openssl dhparam \-out dh\&.pem 2048"\fR\&. If this option is not specified, 2048\-bit MODP Group with 256\-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2\&.3\&.
Whether or not to cache missed lookups\&. When there is an attempt to lookup for a value in a database and this value is not found and the option is set to
\fItrue\fR, this attempt will be cached and no attempts will be performed until the cache expires (see
\fIcache_life_time\fR)\&. Usually you don\(cqt want to change it\&. Default is
A maximum number of items (not memory!) in cache\&. The rule of thumb, for all tables except rosters, you should set it to the number of maximum online users you expect\&. For roster multiply this number by 20 or so\&. If the cache size reaches this threshold, it\(cqs fully cleared, i\&.e\&. all items are deleted, and the corresponding warning is logged\&. You should avoid frequent cache clearance, because this degrades performance\&. The default value is
is replaced with ejabberd version number in semver format when compiled with Elixir\(cqs mix, or XX\&.YY format otherwise\&. Alternatively, it can be the name of a module that implements ejabberd CAPTCHA support\&. There is no default value: when this option is not set, CAPTCHA functionality is completely disabled\&.
The option accepts a list of file paths (optionally with wildcards) containing either PEM certificates or PEM private keys\&. At startup or configuration reload, ejabberd reads all certificates from these files, sorts them, removes duplicates, finds matching private keys and then rebuilds full certificate chains for the use in TLS connections\&. Use this option when TLS is enabled in either of ejabberd listeners:
\fIejabberd_c2s\fR,
\fIejabberd_http\fR
and so on\&. NOTE: if you modify the certificate files or change the value of the option, run
\fIejabberdctl reload\-config\fR
in order to rebuild and reload the certificate chains\&.
A list of Erlang nodes to connect on ejabberd startup\&. This option is mostly intended for ejabberd customization and sophisticated setups\&. The default value is an empty list\&.
Default volatile (in\-memory) storage for ejabberd\&. Modules and other components (e\&.g\&. session management) may have its own value\&. The default value is
\fI\&.\&./configuration/file\-format\&.md#macros\-in\-configuration\-file|macro\fR\&. The value can be any valid arbitrary YAML value\&. For convenience, it\(cqs recommended to define a
in capital letters\&. Duplicated macros are not allowed\&. Macros are processed after additional configuration files have been included, so it is possible to use macros that are defined in configuration files included before the usage\&. It is possible to use a
\fIXEP\-0474: SASL SCRAM Downgrade Protection\fR\&. There are known buggy clients (like those that use strophejs 1\&.6\&.2) which will not be able to authenticatate when servers sends data from that specification\&. This options allows server to disable it to allow even buggy clients connects, but in exchange decrease MITM protection\&. The default value of this option is
the components that are plugged on an ejabberd cluster\&. It means that you can plug one or several instances of the same component on each ejabberd node and that the traffic will be automatically distributed\&. The algorithm to deliver messages to the component(s) can be specified by this option\&. For any component connected as
\fI,\fR) that will be provided by ejabberd when sending ReST requests\&. The default value is an empty string of headers:
\fI""\fR\&.
.RE
.PP
\fBext_api_http_pool_size\fR: \fIpos_integer()\fR
.RS4
Define the size of the HTTP pool, that is, the maximum number of sessions that the ejabberd ReST service will handle simultaneously\&. The default value is:
\fI100\fR\&.
.RE
.PP
\fBext_api_path_oauth\fR: \fIPath\fR
.RS4
Define the base URI path when performing OAUTH ReST requests\&. The default value is:
\fI"/oauth"\fR\&.
.RE
.PP
\fBext_api_url\fR: \fIURL\fR
.RS4
Define the base URI when performing ReST requests\&. The default value is:
This ACL rule defines accounts that can use only the
\fIauthentication\&.md#jwt\-authentication|JWT\fR
auth method, even if others are also defined in the ejabberd configuration file\&. In other words: if there are several auth methods enabled for this host (JWT, SQL, \&...), users that match this rule can only use JWT\&. The default value is
option are reachable, ejabberd connects to these backup servers\&. The default is an empty list, i\&.e\&. no backup servers specified\&. Please notice that ejabberd only connects to the next server when the existing connection is lost; it doesn\(cqt detect when a previously\-attempted server becomes available again\&.
LDAP base directory which stores users accounts\&. There is no default value: you must set the option in order for LDAP connections to work properly\&.
Whether to dereference aliases or not\&. The default value is
\fInever\fR\&.
.RE
.PP
\fBldap_dn_filter\fR: \fI{Filter: FilterAttrs}\fR
.RS4
This filter is applied on the results returned by the main filter\&. The filter performs an additional LDAP lookup to make the complete result\&. This is useful when you are unable to define all filter rules in
\fIldap_filter\fR\&. You can define "%u", "%d", "%s" and "%D" pattern variables in
\fIFilter\fR: "%u" is replaced by a user\(cqs part of the JID, "%d" is replaced by the corresponding domain (virtual host), all "%s" variables are consecutively replaced by values from the attributes in
\fIFilterAttrs\fR
and "%D" is replaced by Distinguished Name from the result set\&. There is no default value, which means the result is not filtered\&. WARNING: Since this filter makes additional LDAP lookups, use it only as the last resort: try to define all filter rules in
\fIldap_filter\fR
option if possible\&.
.sp
\fBExample\fR:
.sp
.ifn\{\
.RS4
.\}
.nf
ldap_dn_filter:
"(&(name=%s)(owner=%D)(user=%u@%d))": [sn]
.fi
.ifn\{\
.RE
.\}
.RE
.PP
\fBldap_encrypt\fR: \fItls | none\fR
.RS4
Whether to encrypt LDAP connection using TLS or not\&. The default value is
\fInone\fR\&. NOTE: STARTTLS encryption is not supported\&.
RFC4515\&. There is no default value\&. Example: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))"\&. NOTE: don\(cqt forget to close brackets and don\(cqt use superfluous whitespaces\&. Also you must not use "uid" attribute in the filter because this attribute will be appended to the filter automatically\&.
A list of IP addresses or DNS names of your LDAP servers (see
\fI\&.\&./configuration/ldap\&.md#ldap\-connection|LDAP connection\fR)\&. ejabberd connects immediately to all of them, and reconnects infinitely if connection is lost\&. The default value is
A path to a file containing PEM encoded CA certificates\&. This option is required when TLS verification is enabled\&.
.RE
.PP
\fBldap_tls_certfile\fR: \fIPath\fR
.RS4
A path to a file containing PEM encoded certificate along with PEM encoded private key\&. This certificate will be provided by ejabberd when TLS enabled for LDAP connections\&. There is no default value, which means no client certificate will be sent\&.
.RE
.PP
\fBldap_tls_depth\fR: \fINumber\fR
.RS4
Specifies the maximum verification depth when TLS verification is enabled, i\&.e\&. how far in a chain of certificates the verification process can proceed before the verification is considered to be failed\&. Peer certificate = 0, CA certificate = 1, higher level CA certificate = 2, etc\&. The value
\fI2\fR
thus means that a chain can at most contain peer cert, CA cert, next CA cert, and an additional CA cert\&. The default value is
\fI1\fR\&.
.RE
.PP
\fBldap_tls_verify\fR: \fIfalse | soft | hard\fR
.RS4
This option specifies whether to verify LDAP server certificate or not when TLS is enabled\&. When
\fIhard\fR
is set, ejabberd doesn\(cqt proceed if the certificate is invalid\&. When
\fIsoft\fR
is set, ejabberd proceeds even if the check has failed\&. The default is
\fIfalse\fR, which means no checks are performed\&.
LDAP attributes which hold a list of attributes to use as alternatives for getting the JID, where
\fIAttr\fR
is an LDAP attribute which holds the user\(cqs part of the JID and
\fIAttrFormat\fR
must contain one and only one pattern variable "%u" which will be replaced by the user\(cqs part of the JID\&. For example, "%u@example\&.org"\&. If the value is in the form of
\fIinfo\fR\&. NOTE: previous versions of ejabberd had log levels defined in numeric format (\fI0\&.\&.5\fR)\&. The numeric values are still accepted for backward compatibility, but are not recommended\&.
.RE
.PP
\fBmax_fsm_queue\fR: \fISize\fR
.RS4
This option specifies the maximum number of elements in the queue of the FSM (Finite State Machine)\&. Roughly speaking, each message in such queues represents one XML stanza queued to be sent into its relevant outgoing stream\&. If queue size reaches the limit (because, for example, the receiver of stanzas is too slow), the FSM and the corresponding connection (if any) will be terminated and error message will be logged\&. The reasonable value for this option depends on your hardware configuration\&. The allowed values are positive integers\&. The default value is
This option can be used to tune tick time parameter of
\fInet_kernel\fR\&. It tells Erlang VM how often nodes should check if intra\-node communication was not interrupted\&. This option must have identical value on all nodes, or it will lead to subtle bugs\&. Usually leaving default value of this is option is best, tweak it only if you know what you are doing\&. The default value is
https://github\&.com/processone/ejabberd/tree/24\&.12/sql\&. There are two schemas available\&. The default legacy schema stores one XMPP domain into one ejabberd database\&. The
schema is best when serving several XMPP domains and/or changing domains from time to time\&. This avoid need to manage several databases and handle complex configuration changes\&. The default depends on configuration flag
\fI\-\-enable\-new\-sql\-schema\fR
which is set at compile time\&.
.RE
.PP
\fBoauth_access\fR: \fIAccessName\fR
.RS4
By default creating OAuth tokens is not allowed\&. To define which users can create OAuth tokens, you can refer to an ejabberd access rule in the
\fIoauth_access\fR
option\&. Use
\fIall\fR
to allow everyone to create tokens\&.
.RE
.PP
\fBoauth_cache_life_time\fR: \fItimeout()\fR
.RS4
Same as
\fIcache_life_time\fR, but applied to OAuth cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBoauth_cache_missed\fR: \fItrue | false\fR
.RS4
Same as
\fIcache_missed\fR, but applied to OAuth cache only\&. If not set, the value from
\fBoauth_client_id_check\fR: \fIallow | db | deny\fR
.RS4
Define whether the client authentication is always allowed, denied, or it will depend if the client ID is present in the database\&. The default value is
Database backend to use for OAuth authentication\&. The default value is picked from
\fIdefault_db\fR
option, or if it\(cqs not set,
\fImnesia\fR
will be used\&.
.RE
.PP
\fBoauth_expire\fR: \fItimeout()\fR
.RS4
Time during which the OAuth token is valid, in seconds\&. After that amount of time, the token expires and the delegated credential cannot be used and is removed from the database\&. The default is
\fI4294967\fR
seconds\&.
.RE
.PP
\fBoauth_use_cache\fR: \fItrue | false\fR
.RS4
Same as
\fIuse_cache\fR, but applied to OAuth cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBoom_killer\fR: \fItrue | false\fR
.RS4
Enable or disable OOM (out\-of\-memory) killer\&. When system memory raises above the limit defined in
\fIoom_watermark\fR
option, ejabberd triggers OOM killer to terminate most memory consuming Erlang processes\&. Note that in order to maintain functionality, ejabberd only attempts to kill transient processes, such as those managing client sessions, s2s or database connections\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBoom_queue\fR: \fISize\fR
.RS4
Trigger OOM killer when some of the running Erlang processes have messages queue above this
\fISize\fR\&. Note that such processes won\(cqt be killed if
\fIoom_killer\fR
option is set to
\fIfalse\fR
or if
\fIoom_watermark\fR
is not reached yet\&.
.RE
.PP
\fBoom_watermark\fR: \fIPercent\fR
.RS4
A percent of total system memory consumed at which OOM killer should be activated with some of the processes possibly be killed (see
\fIoom_killer\fR
option)\&. Later, when memory drops below this
\fIPercent\fR, OOM killer is deactivated\&. The default value is
which means it first tries connecting with IPv6, if that fails it tries using IPv4\&. This option is obsolete and irrelevant when using ejabberd 23\&.01 and Erlang/OTP 22, or newer versions of them\&.
\fImod_register\fR\&. It limits the frequency of registrations from a given IP or username\&. So, a user that tries to register a new account from the same IP address or JID during this time after their previous registration will receive an error with the corresponding explanation\&. To disable this limitation, set the value to
NOTE: this option is deprecated and may be removed anytime in the future versions\&. The possible values match exactly the three possibilities described in
XMPP Core: section 7\&.7\&.2\&.2\&. The default value is
\fIcloseold\fR\&. If the client uses old Jabber Non\-SASL authentication (XEP\-0078), then this option is not respected, and the action performed is
\fIcloseold\fR\&.
.RE
.PP
\fBrouter_cache_life_time\fR: \fItimeout()\fR
.RS4
Same as
\fIcache_life_time\fR, but applied to routing table cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBrouter_cache_missed\fR: \fItrue | false\fR
.RS4
Same as
\fIcache_missed\fR, but applied to routing table cache only\&. If not set, the value from
Database backend to use for routing information\&. The default value is picked from
\fIdefault_ram_db\fR
option, or if it\(cqs not set,
\fImnesia\fR
will be used\&.
.RE
.PP
\fBrouter_use_cache\fR: \fItrue | false\fR
.RS4
Same as
\fIuse_cache\fR, but applied to routing table cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBrpc_timeout\fR: \fItimeout()\fR
.RS4
A timeout for remote function calls between nodes in an ejabberd cluster\&. You should probably never change this value since those calls are used for internal needs only\&. The default value is
Full path to a file containing custom DH parameters to use for s2s connections\&. Such a file could be created with the command
\fI"openssl dhparam \-out dh\&.pem 2048"\fR\&. If this option is not specified, 2048\-bit MODP Group with 256\-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2\&.3\&.
that can be used in other parts of the configuration file, such as
\fIshaper_rules\fR
option\&. The shaper itself is defined by its
\fIRate\fR, where
\fIRate\fR
stands for the maximum allowed incoming rate in
\fBbytes\fR
per second\&. When a connection exceeds this limit, ejabberd stops reading from the socket until the average rate is again below the allowed maximum\&. In the example below shaper
\fInormal\fR
limits the traffic speed to 1,000 bytes/sec and shaper
An interval to make a dummy SQL request to keep alive the connections to the database\&. There is no default value, so no keepalive requests are made\&.
about this option: improved in 20\&.03\&. Whether to use SSL encrypted connections to the SQL server\&. The option is only available for MySQL, MS SQL and PostgreSQL\&. The default value is
\fItrue\fR\&. There is no default which means ejabberd won\(cqt provide a client certificate to the SQL server\&. This option has no effect for MS SQL\&.
to allow all proxies, or specify a list of IPs, possibly with masks\&. The default value is an empty list\&. Using this option you can know the real IP of the request, for admin purpose, or security configuration (for example using
\fImod_fail2ban\fR)\&. IMPORTANT: The proxy MUST be configured to set the
\fIX\-Forwarded\-For\fR
header if you enable this option as, otherwise, the client can set it itself and as a result the IP value cannot be trusted for security rules in ejabberd\&.
about this option: updated in 24\&.06\&. Allow ejabberd to update SQL schema in MySQL, PostgreSQL and SQLite databases\&. This option was added in ejabberd 23\&.10, and enabled by default since 24\&.06\&. The default value is
Whether to validate any incoming XML packet according to the schemas of
supported XMPP extensions\&. WARNING: the validation is only intended for the use by client developers \- don\(cqt enable it in production environment\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBversion\fR: \fIstring()\fR
.RS4
The option can be used to set custom ejabberd version, that will be used by different parts of ejabberd, for example by
\fImod_version\fR
module\&. The default value is obtained at compile time from the underlying version control system\&.
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
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
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
seconds\&.
.RE
.PP
\fBwebsocket_timeout\fR: \fItimeout()\fR
.RS4
Amount of time without any communication after which the connection would be closed\&. The default value is
\fIban_account\fR API: This command kicks all the connected sessions of the account from the server\&. It also changes their password to a randomly generated one, so they can\(cqt login anymore unless a server administrator changes their password again\&. It is possible to define the reason of the ban\&. The new password also includes the reason and the date and time of the ban\&. See an example below\&.
\fIpush_roster\fR API (and \fIpush_roster_all\fR API): The roster file must be placed, if using Windows, on the directory where you installed ejabberd: C:/Program Files/ejabberd or similar\&. If you use other Operating System, place the file on the same directory where the \&.beam files are installed\&. See below an example roster file\&.
\fIsrg_create\fR API: If you want to put a group Name with blank spaces, use the characters \fI"\fR\*(Aq and \fI\*(Aq"\fR to define when the Name starts and ends\&. See an example below\&.
With this call, the sessions of the local account which JID is \fIboby@example\&.org\fR will be kicked, and its password will be set to something like \fIBANNED_ACCOUNT\(em20080425T21:45:07\(em2176635\(emSpammed_rooms\fR
This module can be used to update existing SQL database from the default to the new schema\&. Check the section \fIdatabase\&.md#default\-and\-new\-schemas|Default and New Schemas\fR for details\&. Please note that only MS SQL, MySQL, and PostgreSQL are supported\&. When the module is loaded use \fIupdate_sql\fR API\&.
This module enables configured users to broadcast announcements and to set the message of the day (MOTD)\&. Configured users can perform these actions with an XMPP client either using Ad\-hoc Commands or sending messages to specific JIDs\&.
Note that this module can be resource intensive on large deployments as it may broadcast a lot of messages\&. This module should be disabled for instances of ejabberd with hundreds of thousands users\&.
The Ad\-hoc Commands are listed in the Server Discovery\&. For this feature to work, \fImod_adhoc\fR must be enabled\&.
.sp
The specific JIDs where messages can be sent are listed below\&. The first JID in each entry will apply only to the specified virtual host example\&.org, while the JID between brackets will apply to all virtual hosts in ejabberd:
example\&.org/announce/all (example\&.org/announce/all\-hosts/all):: The message is sent to all registered users\&. If the user is online and connected to several resources, only the resource with the highest priority will receive the message\&. If the registered user is not connected, the message will be stored offline in assumption that offline storage (see
example\&.org/announce/online (example\&.org/announce/all\-hosts/online):: The message is sent to all connected users\&. If the user is online and connected to several resources, all resources will receive the message\&.
example\&.org/announce/motd (example\&.org/announce/all\-hosts/motd):: The message is set as the message of the day (MOTD) and is sent to users when they login\&. In addition the message is sent to all connected users (similar to announce/online)\&.
example\&.org/announce/motd/update (example\&.org/announce/all\-hosts/motd/update):: The message is set as message of the day (MOTD) and is sent to users when they login\&. The message is not sent to any currently connected user\&.
example\&.org/announce/motd/delete (example\&.org/announce/all\-hosts/motd/delete):: Any message sent to this JID removes the existing message of the day (MOTD)\&.
The purpose of the module is to cope with legacy and modern XMPP clients posting avatars\&. The process is described in XEP\-0398: User Avatar to vCard\-Based Avatars Conversion\&.
.sp
Also, the module supports conversion between avatar image formats on the fly\&.
.sp
The module depends on \fImod_vcard\fR, \fImod_vcard_xupdate\fR and \fImod_pubsub\fR\&.
\fIdefault\fR, which is match\-all rule\&. NOTE: the list of supported formats is detected at compile time depending on the image libraries installed in the system\&.
Limit any given JID by the number of avatars it is able to convert per minute\&. This is to protect the server from image conversion DoS\&. The default value is
This module blocks and logs any messages coming from an unknown entity\&. If a writing entity is not in your roster, you can let this module drop and/or log the message\&. By default you\(cqll just not receive message from that entity\&. Enable this module if you want to drop SPAM messages\&.
means the message will be rejected (or a CAPTCHA would be generated for a presence, if configured), and
\fIallow\fR
means the sender is whitelisted and the stanza will pass through\&. The default value is
\fInone\fR, which means nothing is whitelisted\&.
.RE
.PP
\fBallow_local_users\fR: \fItrue | false\fR
.RS4
This option specifies if strangers from the same local host should be accepted or not\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBallow_transports\fR: \fItrue | false\fR
.RS4
If set to
\fItrue\fR
and some server\(cqs JID is in user\(cqs roster, then messages from any user of this server are accepted even if no subscription present\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBcaptcha\fR: \fItrue | false\fR
.RS4
Whether to generate CAPTCHA or not in response to messages from strangers\&. See also section
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\&.
Indicate the maximum length of a temporary session pause (in seconds) that a client can request\&. The default value is
\fI120\fR\&.
.RE
.PP
\fBprebind\fR: \fItrue | false\fR
.RS4
If enabled, the client can create the session without going through authentication\&. Basically, it creates a new session with anonymous authentication\&. The default value is
This module implements XEP\-0115: Entity Capabilities\&. The main purpose of the module is to provide PEP functionality (see \fImod_pubsub\fR)\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.SS"mod_carboncopy"
.sp
The module implements XEP\-0280: Message Carbons\&. The module broadcasts messages on all connected user resources (devices)\&.
.sp
The module has no options\&.
.SS"mod_client_state"
.sp
This module allows for queueing certain types of stanzas when a client indicates that the user is not actively using the client right now (see XEP\-0352: Client State Indication)\&. This can save bandwidth and resources\&.
.sp
A stanza is dropped from the queue if it\(cqs effectively obsoleted by a new one (e\&.g\&., a new presence stanza would replace an old one from the same client)\&. The queue is flushed if a stanza arrives that won\(cqt be queued, or if the queue size reaches a certain limit (currently 100 stanzas), or if the client becomes active again\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBqueue_chat_states\fR: \fItrue | false\fR
.RS4
Queue "standalone" chat state notifications (as defined in
XEP\-0085: Chat State Notifications) while a client indicates inactivity\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBqueue_pep\fR: \fItrue | false\fR
.RS4
Queue PEP notifications while a client is inactive\&. When the queue is flushed, only the most recent notification of a given PEP node is delivered\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBqueue_presence\fR: \fItrue | false\fR
.RS4
While a client is inactive, queue presence stanzas that indicate (un)availability\&. The default value is
The module provides server configuration functionality via XEP\-0050: Ad\-Hoc Commands\&. Implements many commands as defined in XEP\-0133: Service Administration\&. This module requires \fImod_adhoc\fR to be loaded\&.
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 → \fIlisten\-options\&.md#request_handlers|request_handlers\fR\&.
This module is an implementation of XEP\-0355: Namespace Delegation\&. Only admin mode has been implemented by now\&. Namespace delegation allows external services to handle IQ using specific namespace\&. This may be applied for external PEP service\&.
Security issue: Namespace delegation gives components access to sensitive data, so permission should be granted carefully, only if you trust the component\&.
.sp.5v
.RE
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
This module is complementary to \fImod_privilege\fR but can also be used separately\&.
Make sure you do not delegate the same namespace to several services at the same time\&. As in the example provided later, to have the \fIsat\-pubsub\&.example\&.org\fR component perform correctly disable the \fImod_pubsub\fR module\&.
This module adds support for XEP\-0030: Service Discovery\&. With this module enabled, services on your server can be discovered by XMPP clients\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBextra_domains\fR: \fI[Domain, \&.\&.\&.]\fR
.RS4
With this option, you can specify a list of extra domains that are added to the Service Discovery item list\&. The default value is an empty list\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS4
A name of the server in the Service Discovery\&. This will only be displayed by special XMPP clients\&. The default value is
\fIejabberd\fR\&.
.RE
.PP
\fBserver_info\fR: \fI[Info, \&.\&.\&.]\fR
.RS4
Specify additional information about the server, as described in
XEP\-0157: Contact Addresses for XMPP Services\&. Every
\fIInfo\fR
element in the list is constructed from the following options:
.PP
\fBmodules\fR: \fIall | [Module, \&.\&.\&.]\fR
.RS4
The value can be the keyword
\fIall\fR, in which case the information is reported in all the services, or a list of ejabberd modules, in which case the information is only specified for the services provided by those modules\&.
The module bans IPs that show the malicious signs\&. Currently only C2S authentication failures are detected\&.
.sp
Unlike the standalone program, \fImod_fail2ban\fR clears the record of authentication failures after some time since the first failure or on a successful authentication\&. It also does not simply block network traffic, but provides the client with a descriptive error message\&.
You should not use this module behind a proxy or load balancer\&. ejabberd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer\&. You can lock all your user base out of ejabberd when using this module behind a proxy\&.
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 → \fIlisten\-options\&.md#request_handlers|request_handlers\fR\&.
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 → \fIlisten\-options\&.md#request_handlers|request_handlers\fR\&.
What API version to use when none is specified in the URL path\&. If setting an ejabberd version, it will use the latest API version that was available in that ejabberd version\&. For example, setting
\fI"24\&.06"\fR
in this option implies
\fI2\fR\&. The default value is the latest version\&.
Specify mappings of extension to content type\&. There are several content types already defined\&. With this option you can add new definitions or modify existing ones\&. The default values are:
Indicate custom HTTP headers to be included in all responses\&. There are no custom headers by default\&.
.RE
.PP
\fBdefault_content_type\fR: \fIType\fR
.RS4
Specify the content type to use for unknown extensions\&. The default value is
\fIapplication/octet\-stream\fR\&.
.RE
.PP
\fBdirectory_indices\fR: \fI[Index, \&.\&.\&.]\fR
.RS4
Indicate one or more directory index files, similarly to Apache\(cqs
\fIDirectoryIndex\fR
variable\&. When an HTTP request hits a directory instead of a regular file, those directory indices are looked in order, and the first one found is returned\&. The default value is an empty list\&.
.RE
.PP
\fBdocroot\fR: \fIPath\fR
.RS4
Directory to serve the files from\&. This is a mandatory option\&.
This example configuration will serve the files from the local directory \fI/var/www\fR in the address \fIhttp://example\&.org:5280/pub/content/\fR\&. In this example a new content type \fIogg\fR is defined, \fIpng\fR is redefined, and \fIjpg\fR definition is deleted:
This module allows for requesting permissions to upload a file via HTTP as described in XEP\-0363: HTTP File Upload\&. If the request is accepted, the client receives a URL for uploading the file and another URL from which that file can later be downloaded\&.
In order to use this module, it must be enabled in \fIlisten\fR → \fIejabberd_http\fR → \fIlisten\-options\&.md#request_handlers|request_handlers\fR\&.
This option makes it possible to offload all HTTP Upload processing to a separate HTTP server\&. Both ejabberd and the HTTP server should share this secret and behave exactly as described at
This option specifies whether ejabberd should create thumbnails of uploaded images\&. If a thumbnail is created, a <thumbnail/> element that contains the download <uri/> and some metadata is returned with the PUT response\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBvcard\fR: \fIvCard\fR
.RS4
A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery\&. The value of
\fIvCard\fR
is a YAML map constructed from an XML representation of vCard\&. Since the representation has no attributes, the mapping is straightforward\&.
This option defines which access rule is used to specify the "hard quota" for the matching JIDs\&. That rule must yield a positive number for any JID that is supposed to have a quota limit\&. This is the number of megabytes a corresponding user may upload\&. When this threshold is exceeded, ejabberd deletes the oldest files uploaded by that user until their disk usage equals or falls below the specified soft quota (see also option
This option defines which access rule is used to specify the "soft quota" for the matching JIDs\&. That rule must yield a positive number of megabytes for any JID that is supposed to have a quota limit\&. See the description of the
\fIaccess_hard_quota\fR
option for details\&. The default value is
\fIsoft_upload_quota\fR\&.
.RE
.PP
\fBmax_days\fR: \fIDays\fR
.RS4
If a number larger than zero is specified, any files (and directories) older than this number of days are removed from the subdirectories of the
Notice it\(cqs not necessary to specify the \fIaccess_hard_quota\fR and \fIaccess_soft_quota\fR options in order to use the quota feature\&. You can stick to the default names and just specify access rules such as those in this example:
This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format\&. This might be useful for clients in certain constrained environments, or for testing purposes\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS4
This option defines which access rule will be used to control who is allowed to use this service\&. The default value is
\fIlocal\fR\&.
.RE
.RE
.SS"mod_last"
.sp
This module adds support for XEP\-0012: Last Activity\&. It can be used to discover when a disconnected user last accessed the server, to know when a connected user was last active on the server, or to query the uptime of the ejabberd server\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.SS"mod_legacy_auth"
.sp
The module implements XEP\-0078: Non\-SASL Authentication\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
This type of authentication was obsoleted in 2008 and you unlikely need this module unless you have something like outdated Jabber bots\&.
This module implements XEP\-0313: Message Archive Management and XEP\-0441: Message Archive Management Preferences\&. Compatible XMPP clients can use it to store their chat history on the server\&.
This option determines how ejabberd\(cqs stream management code (see
\fImod_stream_mgmt\fR) handles unacknowledged messages when the connection is lost\&. Usually, such messages are either bounced or resent\&. However, neither is done for messages that were stored in the user\(cqs MAM archive if this option is set to
\fItrue\fR\&. In this case, ejabberd assumes those messages will be retrieved from the archive\&. The default value is
\fImod_muc\fR) when it gets destroyed\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBcompress_xml\fR: \fItrue | false\fR
.RS4
When enabled, new messages added to archives are compressed using a custom compression algorithm\&. This feature works only with SQL backends\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBdefault\fR: \fIalways | never | roster\fR
.RS4
The option defines default policy for chat history\&. When
\fIalways\fR
is set every chat message is stored\&. With
\fIroster\fR
only chat history with contacts from user\(cqs roster is stored\&. And
\fInever\fR
fully disables chat history\&. Note that a client can change its policy via protocol commands\&. The default value is
When this option is disabled, for each individual subscriber a separate mucsub message is stored\&. With this option enabled, when a user fetches archive virtual mucsub, messages are generated from muc archives\&. The default value is
\fItrue\fR, all packets failing to be delivered via an XMPP server\-to\-server connection will then be routed to the Matrix gateway by translating a Jabber ID
\fIfalse\fR, messages must be explicitly sent to the matrix gateway service Jabber ID to be routed to a remote Matrix server\&. In this case, to send a message to Matrix user
This module is an experimental implementation of XEP\-0369: Mediated Information eXchange (MIX)\&. It\(cqs asserted that the MIX protocol is going to replace the MUC protocol in the future (see \fImod_muc\fR)\&.
.sp
To learn more about how to use that feature, you can refer to our tutorial: \fI\&.\&./\&.\&./tutorials/mix\-010\&.md|Getting started with MIX\fR
A name of the service in the Service Discovery\&. This will only be displayed by special XMPP clients\&. The default value is
\fIChannels\fR\&.
.RE
.RE
.SS"mod_mix_pam"
.sp
This module implements XEP\-0405: Mediated Information eXchange (MIX): Participant Server Requirements\&. The module is needed if MIX compatible clients on your server are going to join MIX channels (either on your server or on any remote servers)\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
\fImod_mix\fR is not required for this module to work, however, without \fImod_mix_pam\fR the MIX functionality of your local XMPP clients will be impaired\&.
This module adds \fI\&.\&./guide/mqtt/index\&.md|support for the MQTT\fR protocol version \fI3\&.1\&.1\fR and \fI5\&.0\fR\&. Remember to configure \fImod_mqtt\fR in \fImodules\fR and \fIlisten\fR sections\&.
This module adds ability to synchronize local MQTT topics with data on remote servers It can update topics on remote servers when local user updates local topic, or can subscribe for changes on remote server, and update local copy when remote data is updated\&. It is available since ejabberd 23\&.01\&.
This module provides support for XEP\-0045: Multi\-User Chat\&. Users can discover existing rooms, join or create them\&. Occupants of a room can chat in public or have private chats\&.
The MUC service allows any Jabber ID to register a nickname, so nobody else can use that nickname in any room in the MUC service\&. To register a nickname, open the Service Discovery in your XMPP client and register in the MUC service\&.
It is also possible to register a nickname in a room, so nobody else can use that nickname in that room\&. If a nick is registered in the MUC service, that nick cannot be registered in any room, and vice versa: a nick that is registered in a room cannot be registered at the MUC service\&.
This module supports clustering and load balancing\&. One module can be started per cluster node\&. Rooms are distributed at creation time on all available MUC module instances\&. The multi\-user chat module is clustered but the rooms themselves are not clustered nor fault\-tolerant: if the node managing a set of rooms goes down, the rooms disappear and they will be recreated on an available node on first connection attempt\&.
You can specify who is allowed to use the Multi\-User Chat service\&. By default everyone is allowed to use it\&.
.RE
.PP
\fBaccess_admin\fR: \fIAccessName\fR
.RS4
This option specifies who is allowed to administrate the Multi\-User Chat service\&. The default value is
\fInone\fR, which means that only the room creator can administer their room\&. The administrators can send a normal message to the service JID, and it will be shown in all active rooms as a service message\&. The administrators can send a groupchat message to the JID of an active room, and the message will be shown in the room as a service message\&.
about this option: improved in 23\&.10\&. This option specifies who is allowed to register nickname within the Multi\-User Chat service and rooms\&. The default is
Define the default room options\&. Note that the creator of a room can modify the options of his room at any time using an XMPP client with MUC capability\&. The
Allow visitors to change nickname\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBallow_visitor_status\fR: \fItrue | false\fR
.RS4
Allow visitors to send status text in presence updates\&. If disallowed, the status text is stripped before broadcasting the presence update to all the room occupants\&. The default value is
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
\fItrue\fR\&.
.RE
.PP
\fBcaptcha_protected\fR: \fItrue | false\fR
.RS4
When a user tries to join a room where they have no affiliation (not owner, admin or member), the room requires them to fill a CAPTCHA challenge (see section
List of roles for which presence is broadcasted\&. The list can contain one or several of:
\fImoderator\fR,
\fIparticipant\fR,
\fIvisitor\fR\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.ifn\{\
.RS4
.\}
.nf
presence_broadcast:
\- moderator
\- participant
\- visitor
.fi
.ifn\{\
.RE
.\}
.RE
.PP
\fBpublic\fR: \fItrue | false\fR
.RS4
The room is public in the list of the MUC service, so it can be discovered\&. MUC admins and room participants will see private rooms in Service Discovery if their XMPP client supports this feature\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBpublic_list\fR: \fItrue | false\fR
.RS4
The list of participants is public, without requiring to enter the room\&. The default value is
A small history of the current discussion is sent to users when they enter the room\&. With this option you can define the number of history messages to keep and send to users joining the room\&. The value is a non\-negative integer\&. Setting the value to
\fI0\fR
disables the history feature and, as a result, nothing is kept in memory\&. The default value is
\fI20\fR\&. This value affects all rooms on the service\&. NOTE: modern XMPP clients rely on Message Archives (XEP\-0313), so feel free to disable the history feature if you\(cqre only using modern clients and have
about this option: added in 21\&.01\&. This option defines the maximum number of characters that Captcha Whitelist can have when configuring the room\&. The default value is
about this option: added in 21\&.01\&. This option defines the maximum number of characters that Password can have when configuring the room\&. The default value is
This option defines the maximum number of characters that Room Description can have when configuring the room\&. The default value is
\fIinfinity\fR\&.
.RE
.PP
\fBmax_room_id\fR: \fINumber\fR
.RS4
This option defines the maximum number of characters that Room ID can have when creating a new room\&. The default value is
\fIinfinity\fR\&.
.RE
.PP
\fBmax_room_name\fR: \fINumber\fR
.RS4
This option defines the maximum number of characters that Room Name can have when configuring the room\&. The default value is
\fIinfinity\fR\&.
.RE
.PP
\fBmax_rooms_discoitems\fR: \fINumber\fR
.RS4
When there are more rooms than this
\fINumber\fR, only the non\-empty ones are returned in a Service Discovery query\&. The default value is
\fI100\fR\&.
.RE
.PP
\fBmax_user_conferences\fR: \fINumber\fR
.RS4
This option defines the maximum number of rooms that any given user can join\&. The default value is
\fI100\fR\&. This option is used to prevent possible abuses\&. Note that this is a soft limit: some users can sometimes join more conferences in cluster configurations\&.
.RE
.PP
\fBmax_users\fR: \fINumber\fR
.RS4
This option defines at the service level, the maximum number of users allowed per room\&. It can be lowered in each room configuration but cannot be increased in individual room configuration\&. The default value is
\fI200\fR\&.
.RE
.PP
\fBmax_users_admin_threshold\fR: \fINumber\fR
.RS4
This option defines the number of service admins or room owners allowed to enter the room when the maximum number of allowed occupants was reached\&. The default limit is
This option defines after how many users in the room, it is considered overcrowded\&. When a MUC room is considered overcrowded, presence broadcasts are limited to reduce load, traffic and excessive presence "storm" received by participants\&. The default value is
This option defines the minimum interval between two messages send by an occupant in seconds\&. This option is global and valid for all rooms\&. A decimal value can be used\&. When this option is not defined, message rate is not limited\&. This feature can be used to protect a MUC service from occupant abuses and limit number of messages that will be broadcasted by the service\&. A good value for this minimum message interval is
\fI0\&.4\fR
second\&. If an occupant tries to send messages faster, an error is send back explaining that the message has been discarded and describing the reason why the message is not acceptable\&.
This option defines the minimum of time between presence changes coming from a given occupant in seconds\&. This option is global and valid for all rooms\&. A decimal value can be used\&. When this option is not defined, no restriction is applied\&. This option can be used to protect a MUC service for occupants abuses\&. If an occupant tries to change its presence more often than the specified interval, the presence is cached by ejabberd and only the last presence is broadcasted to all occupants in the room after expiration of the interval delay\&. Intermediate presence packets are silently discarded\&. A good value for this option is
The value of the service name\&. This name is only visible in some clients that support
XEP\-0030: Service Discovery\&. The default is
\fIChatrooms\fR\&.
.RE
.PP
\fBpreload_rooms\fR: \fItrue | false\fR
.RS4
Whether to load all persistent rooms in memory on startup\&. If disabled, the room is only loaded on first participant join\&. The default is
\fItrue\fR\&. It makes sense to disable room preloading when the number of rooms is high: this will improve server startup time and memory consumption\&.
This module provides commands to administer local MUC services and their MUC rooms\&. It also provides simple WebAdmin pages to view the existing rooms\&.
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\&.
.sp
Features:
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Room details are added on top of each page: room title, JID, author, subject and configuration\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
The room JID in the generated HTML is a link to join the room (using XMPP URI)\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Subject and room configuration changes are tracked and displayed\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Joins, leaves, nick changes, kicks, bans and
\fI/me\fR
are tracked and displayed, including the reason if available\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Generated HTML files are XHTML 1\&.0 Transitional and CSS compliant\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Timestamps are self\-referencing links\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Links on top for quicker navigation: Previous day, Next day, Up\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
CSS is used for style definition, and a custom CSS file can be used\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
URLs on messages and subjects are converted to hyperlinks\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Timezone used on timestamps is shown on the log files\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
A custom link can be added on top of each page\&.
.RE
.sp
The module depends on \fImod_muc\fR\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBaccess_log\fR: \fIAccessName\fR
.RS4
This option restricts which occupants are allowed to enable or disable room logging\&. The default value is
\fImuc_admin\fR\&. NOTE: for this default setting you need to have an access rule for
\fImuc_admin\fR
in order to take effect\&.
.RE
.PP
\fBcssfile\fR: \fIPath | URL\fR
.RS4
With this option you can set whether the HTML files should have a custom CSS file or if they need to use the embedded CSS\&. Allowed values are either
\fIPath\fR
to local file or an
\fIURL\fR
to a remote file\&. By default a predefined CSS will be embedded into the HTML page\&.
\fIroom_jid\fR, the room directory name will be the full room JID\&. Otherwise, the room directory name will be only the room name, not including the MUC service name\&. The default value is
\fIroom_jid\fR\&.
.RE
.PP
\fBdirtype\fR: \fIsubdirs | plain\fR
.RS4
The type of the created directories can be specified with this option\&. If set to
\fIsubdirs\fR, subdirectories are created for each year and month\&. Otherwise, the names of the log files contain the full date, and there are no subdirectories\&. The default value is
Define the permissions that must be used when creating the log files: the number of the mode, and the numeric id of the group that will own the files\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.ifn\{\
.RS4
.\}
.nf
file_permissions:
mode: 644
group: 33
.fi
.ifn\{\
.RE
.\}
.RE
.PP
\fBoutdir\fR: \fIPath\fR
.RS4
This option sets the full path to the directory in which the HTML files should be stored\&. Make sure the ejabberd daemon user has write access on that directory\&. The default value is
\fIwww/muc\fR\&.
.RE
.PP
\fBspam_prevention\fR: \fItrue | false\fR
.RS4
If set to
\fItrue\fR, a special attribute is added to links that prevent their indexation by search engines\&. The default value is
\fItrue\fR, which mean that
\fInofollow\fR
attributes will be added to user submitted links\&.
.RE
.PP
\fBtimezone\fR: \fIlocal | universal\fR
.RS4
The time zone for the logs is configurable with this option\&. If set to
\fIlocal\fR, the local time, as reported to Erlang emulator by the operating system, will be used\&. Otherwise, UTC time will be used\&. The default value is
\fIlocal\fR\&.
.RE
.PP
\fBtop_link\fR: \fI{URL: Text}\fR
.RS4
With this option you can customize the link on the top right corner of each log file\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.ifn\{\
.RS4
.\}
.nf
top_link:
/: Home
.fi
.ifn\{\
.RE
.\}
.RE
.PP
\fBurl\fR: \fIURL\fR
.RS4
A top level
\fIURL\fR
where a client can access logs of a particular conference\&. The conference name is appended to the URL if
Service name to provide in the Info query to the Service Discovery\&. Default is
\fI"Multicast"\fR\&.
.RE
.PP
\fBvcard\fR
.RS4
vCard element to return when queried\&. Default value is
\fIundefined\fR\&.
.RE
.RE
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBExample:\fR
.RS4
.sp
.ifn\{\
.RS4
.\}
.nf
# Only admins can send packets to multicast service
access_rules:
multicast:
\- allow: admin
# If you want to allow all your users:
access_rules:
multicast:
\- allow
# This allows both admins and remote users to send packets,
# but does not allow local users
acl:
allservers:
server_glob: "*"
access_rules:
multicast:
\- allow: admin
\- deny: local
\- allow: allservers
modules:
mod_multicast:
host: multicast\&.example\&.org
access: multicast
limits:
local:
message: 40
presence: infinite
remote:
message: 150
.fi
.ifn\{\
.RE
.\}
.RE
.SS"mod_offline"
.sp
This module implements XEP\-0160: Best Practices for Handling Offline Messages and XEP\-0013: Flexible Offline Message Retrieval\&. This means that all messages sent to an offline user will be stored on the server until that user comes online again\&. Thus it is very similar to how email works\&. A user is considered offline if no session presence priority > 0 are currently open\&.
This option defines which access rule will be enforced to limit the maximum number of offline messages that a user can have (quota)\&. When a user has too many offline messages, any new messages that they receive are discarded, and a
\fI<resource\-constraint/>\fR
error is returned to the sender\&. The default value is
This option is use the disable an optimization that avoids bouncing error messages when groupchat messages could not be stored as offline\&. It will reduce chat room load, without any drawback in standard use cases\&. You may change default value only if you have a custom module which uses offline hook after
\fImod_offline\fR\&. This option can be useful for both standard MUC and MucSub, but the bounce is much more likely to happen in the context of MucSub, so it is even more important to have it on large MucSub services\&. The default value is
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
This module implements support for XEP\-0199: XMPP Ping and periodic keepalives\&. When this module is enabled ejabberd responds correctly to ping requests, as defined by the protocol\&.
How often to send pings to connected clients, if option
\fIsend_pings\fR
is set to
\fItrue\fR\&. If a client connection does not send or receive any stanza within this interval, a ping request is sent to the client\&. The default value is
\fI1\fR
minute\&.
.RE
.PP
\fBsend_pings\fR: \fItrue | false\fR
.RS4
If this option is set to
\fItrue\fR, the server sends pings to connected clients that are not active in a given interval defined in
\fIping_interval\fR
option\&. This is useful to keep client connections alive or checking availability\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBtimeout_action\fR: \fInone | kill\fR
.RS4
What to do when a client does not answer to a server ping request in less than period defined in
is loaded and stream management is enabled by a client, killing the client connection doesn\(cqt mean killing the client session \- the session will be kept alive in order to give the client a chance to resume it\&. The default value is
This module detects flood/spam in presence subscriptions traffic\&. If a user sends or receives more of those stanzas in a given time interval, the exceeding stanzas are silently dropped, and a warning is logged\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBcount\fR: \fINumber\fR
.RS4
The number of subscription presence stanzas (subscribe, unsubscribe, subscribed, unsubscribed) allowed for any direction (input or output) per time defined in
\fIinterval\fR
option\&. Please note that two users subscribing to each other usually generate 4 stanzas, so the recommended value is
\fI4\fR
or more\&. The default value is
\fI5\fR\&.
.RE
.PP
\fBinterval\fR: \fItimeout()\fR
.RS4
The time interval\&. The default value is
\fI1\fR
minute\&.
.RE
.RE
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBExample:\fR
.RS4
.sp
.ifn\{\
.RS4
.\}
.nf
modules:
mod_pres_counter:
count: 5
interval: 30 secs
.fi
.ifn\{\
.RE
.\}
.RE
.SS"mod_privacy"
.sp
This module implements XEP\-0016: Privacy Lists\&.
Nowadays modern XMPP clients rely on XEP\-0191: Blocking Command which is implemented by \fImod_blocking\fR\&. However, you still need \fImod_privacy\fR loaded in order for \fImod_blocking\fR to work\&.
This module adds support for XEP\-0049: Private XML Storage\&.
.sp
Using this method, XMPP entities can store private data on the server, retrieve it whenever necessary and share it between multiple connected clients of the same user\&. The data stored might be anything, as long as it is a valid XML\&. One typical usage is storing a bookmark of all user\(cqs conferences (XEP\-0048: Bookmarks)\&.
This module is an implementation of XEP\-0356: Privileged Entity\&. This extension allows components to have privileged access to other entity data (send messages on behalf of the server or on behalf of a user, get/set user roster, access presence information, etc\&.)\&. This may be used to write powerful external components, for example implementing an external PEP or MAM service\&.
.sp
By default a component does not have any privileged access\&. It is worth noting that the permissions grant access to the component to a specific data type for all users of the virtual host on which \fImod_privilege\fR is loaded\&.
Make sure you have a listener configured to connect your component\&. Check the section about listening ports for more information\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBWarning\fR
.ps-1
.br
.sp
Security issue: Privileged access gives components access to sensitive data, so permission should be granted carefully, only if you trust a component\&.
This option defines permissions for messages\&. By default no permissions are given\&. The
\fIOptions\fR
are:
.PP
\fBoutgoing\fR: \fIAccessName\fR
.RS4
The option defines an access rule for sending outgoing messages by the component\&. The default value is
\fInone\fR\&.
.RE
.RE
.PP
\fBpresence\fR: \fIOptions\fR
.RS4
This option defines permissions for presences\&. By default no permissions are given\&. The
\fIOptions\fR
are:
.PP
\fBmanaged_entity\fR: \fIAccessName\fR
.RS4
An access rule that gives permissions to the component to receive server presences\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBroster\fR: \fIAccessName\fR
.RS4
An access rule that gives permissions to the component to receive the presence of both the users and the contacts in their roster\&. The default value is
\fInone\fR\&.
.RE
.RE
.PP
\fBroster\fR: \fIOptions\fR
.RS4
This option defines roster permissions\&. By default no permissions are given\&. The
\fIOptions\fR
are:
.PP
\fBboth\fR: \fIAccessName\fR
.RS4
Sets read/write access to a user\(cqs roster\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBget\fR: \fIAccessName\fR
.RS4
Sets read access to a user\(cqs roster\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBset\fR: \fIAccessName\fR
.RS4
Sets write access to a user\(cqs roster\&. The default value is
A size of the buffer for incoming packets\&. If you define a shaper, set the value of this option to the size of the shaper in order to avoid traffic spikes in file transfers\&. The default value is
\fI65536\fR
bytes\&.
.RE
.PP
\fBshaper\fR: \fIShaper\fR
.RS4
This option defines a shaper for the file transfer peers\&. A shaper with the maximum bandwidth will be selected\&. The default is
\fInone\fR, i\&.e\&. no shaper\&.
.RE
.PP
\fBsndbuf\fR: \fISize\fR
.RS4
A size of the buffer for outgoing packets\&. If you define a shaper, set the value of this option to the size of the shaper in order to avoid traffic spikes in file transfers\&. The default value is
\fI65536\fR
bytes\&.
.RE
.PP
\fBvcard\fR: \fIvCard\fR
.RS4
A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery\&. The value of
\fIvCard\fR
is a YAML map constructed from an XML representation of vCard\&. Since the representation has no attributes, the mapping is straightforward\&.
This module offers a service for XEP\-0060: Publish\-Subscribe\&. The functionality in \fImod_pubsub\fR can be extended using plugins\&. The plugin that implements PEP (XEP\-0163: Personal Eventing via Pubsub) is enabled in the default ejabberd configuration file, and it requires \fImod_caps\fR\&.
To override default node configuration, regardless of node plugin\&. Value is a list of key\-value definition\&. Node configuration still uses default configuration defined by node plugin, and overrides any items by value defined in this configurable list\&.
\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 you to raise the user connection rate\&. The cost is memory usage, as every item is stored in memory\&.
The maximum number of nodes to return in a discoitem response\&. The default value is:
\fI100\fR\&.
.RE
.PP
\fBmax_subscriptions_node\fR: \fIMaxSubs\fR
.RS4
Define the maximum number of subscriptions managed by a node\&. Default value is no limitation:
\fIundefined\fR\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS4
The value of the service name\&. This name is only visible in some clients that support
XEP\-0030: Service Discovery\&. The default is
\fIvCard User Search\fR\&.
.RE
.PP
\fBnodetree\fR: \fINodetree\fR
.RS4
To specify which nodetree to use\&. If not defined, the default pubsub nodetree is used:
\fItree\fR\&. Only one nodetree can be used per host, and is shared by all node plugins\&.
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
\fItree\fR
nodetree store node configuration and relations on the database\&.
\fIflat\fR
nodes are stored without any relationship, and
\fIhometree\fR
nodes can have child nodes\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
\fIvirtual\fR
nodetree does not store nodes on database\&. This saves resources on systems with tons of nodes\&. If using the
\fIvirtual\fR
nodetree, you can only enable those node plugins:
\fI[flat, pep]\fR
or
\fI[flat]\fR; any other plugins configuration will not work\&. Also, all nodes will have the default configuration, and this can not be changed\&. Using
\fIvirtual\fR
nodetree requires to start from a clean database, it will not work if you used the default
To specify which pubsub node plugins to use\&. The first one in the list is used by default\&. If this option is not defined, the default plugins list is:
\fI[flat]\fR\&. PubSub clients can define which plugin to use when creating a node: add
\fItype=\*(Aqplugin\-name\fR\*(Aq attribute to the
\fIcreate\fR
stanza element\&.
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
\fIflat\fR
plugin handles the default behaviour and follows standard XEP\-0060 implementation\&.
Example of configuration that uses flat nodes as default, and allows use of flat, hometree and pep nodes:
.sp
.ifn\{\
.RS4
.\}
.nf
modules:
mod_pubsub:
access_createnode: pubsub_createnode
max_subscriptions_node: 100
default_node_config:
notification_type: normal
notify_retract: false
max_items: 4
plugins:
\- flat
\- pep
.fi
.ifn\{\
.RE
.\}
.sp
Using relational database requires using mod_pubsub with db_type \fIsql\fR\&. Only flat, hometree and pep plugins supports SQL\&. The following example shows previous configuration with SQL usage:
This module implements the XMPP server\(cqs part of the push notification solution specified in XEP\-0357: Push Notifications\&. It does not generate, for example, APNS or FCM notifications directly\&. Instead, it\(cqs designed to work with so\-called "app servers" operated by third\-party vendors of mobile apps\&. Those app servers will usually trigger notification delivery to the user\(cqs mobile device using platform\-dependent backend services such as FCM or APNS\&.
\fItrue\fR, the message text is included with push notifications generated for incoming messages with a body\&. The option can instead be set to a static
\fIText\fR, in which case the specified text will be included in place of the actual message body\&. This can be useful to signal the app server whether the notification was triggered by a message with body (as opposed to other types of traffic) without leaking actual message contents\&. The default value is "New message"\&.
.RE
.PP
\fBinclude_sender\fR: \fItrue | false\fR
.RS4
If this option is set to
\fItrue\fR, the sender\(cqs JID is included with push notifications generated for incoming messages with a body\&. The default value is
This module tries to keep the stream management session (see \fImod_stream_mgmt\fR) of a disconnected mobile client alive if the client enabled push notifications for that session\&. However, the normal session resumption timeout is restored once a push notification is issued, so the session will be closed if the client doesn\(cqt respond to push notifications\&.
This option specifies the period of time until the session of a disconnected push client times out\&. This timeout is only in effect as long as no push notification is issued\&. Once that happened, the resumption timeout configured for
registered push clients during server startup\&. This option should not be enabled on servers with many push clients as it can generate significant load on the involved push services and the server itself\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBwake_on_timeout\fR: \fItrue | false\fR
.RS4
If this option is set to
\fItrue\fR, a notification is generated shortly before the session would time out as per the
This module reads also the top\-level \fIregistration_timeout\fR option defined globally for the server, so please check that option documentation too\&.
doesn\(cqt allow the client to register new accounts from s2s or existing c2s sessions\&. You can change it by defining access rule in this option\&. Use with care: allowing registration from s2s leads to uncontrolled massive accounts creation by rogue users\&.
This module supports \fIbasic\&.md#captcha|CAPTCHA\fR to register a new account\&. To enable this feature, configure the top\-level \fIcaptcha_cmd\fR and top\-level \fIcaptcha_url\fR options\&.
As an example usage, the users of the host \fIlocalhost\fR can visit the page: \fIhttps://localhost:5280/register/\fR It is important to include the last / character in the URL, otherwise the subpages URL will be incorrect\&.
This module is enabled in \fIlisten\fR → \fIejabberd_http\fR → \fIlisten\-options\&.md#request_handlers|request_handlers\fR, no need to enable in \fImodules\fR\&. The module depends on \fImod_register\fR where all the configuration is performed\&.
This module implements roster management as defined in RFC6121 Section 2\&. The module also adds support for XEP\-0237: Roster Versioning\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS4
This option can be configured to specify rules to restrict roster management\&. If the rule returns
\fIdeny\fR
on the requested user name, that user cannot modify their personal roster, i\&.e\&. they cannot add/remove/modify contacts or send presence subscriptions\&. The default value is
\fIall\fR, i\&.e\&. no restrictions\&.
.RE
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBstore_current_id\fR: \fItrue | false\fR
.RS4
If this option is set to
\fItrue\fR, the current roster version number is stored on the database\&. If set to
\fIfalse\fR, the roster version number is calculated on the fly each time\&. Enabling this option reduces the load for both ejabberd and the database\&. This option does not affect the client in any way\&. This option is only useful if option
\fIversioning\fR
is set to
\fItrue\fR\&. The default value is
\fIfalse\fR\&. IMPORTANT: if you use
\fImod_shared_roster\fR
or
\fImod_shared_roster_ldap\fR, you must set the value of the option to
\fIfalse\fR\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.PP
\fBversioning\fR: \fItrue | false\fR
.RS4
Enables/disables Roster Versioning\&. The default value is
The module adds support for XEP\-0288: Bidirectional Server\-to\-Server Connections that allows using single s2s connection to communicate in both directions\&.
The module adds support for XEP\-0220: Server Dialback to provide server identity verification based on DNS\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBWarning\fR
.ps-1
.br
.sp
DNS\-based verification is vulnerable to DNS cache poisoning, so modern servers rely on verification based on PKIX certificates\&. Thus this module is only recommended for backward compatibility with servers running outdated software or non\-TLS servers, or those with invalid certificates (as long as you accept the risks, e\&.g\&. you assume that the remote server has an invalid certificate due to poor administration and not because it\(cqs compromised)\&.
.sp.5v
.RE
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS4
An access rule that can be used to restrict dialback for some servers\&. The default value is
This module forwards copies of all stanzas to remote XMPP servers or components\&. Every stanza is encapsulated into <forwarded/> element as described in XEP\-0297: Stanza Forwarding\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBloggers\fR: \fI[Domain, \&.\&.\&.]\fR
.RS4
A list of servers or connected components to which stanzas will be forwarded\&.
.RE
.RE
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBExample:\fR
.RS4
.sp
.ifn\{\
.RS4
.\}
.nf
modules:
mod_service_log:
loggers:
\- xmpp\-server\&.tld
\- component\&.domain\&.tld
.fi
.ifn\{\
.RE
.\}
.RE
.SS"mod_shared_roster"
.sp
This module enables you to create shared roster groups: groups of accounts that can see members from (other) groups in their rosters\&.
.sp
The big advantages of this feature are that end users do not need to manually add all users to their rosters, and that they cannot permanently delete users from the shared roster groups\&. A shared roster group can have members from any XMPP server, but the presence will only be available from and to members of the same virtual host where the group is created\&. It still allows the users to have / add their own contacts, as it does not replace the standard roster\&. Instead, the shared roster contacts are merged to the relevant users at retrieval time\&. The standard user rosters thus stay unmodified\&.
Shared roster groups can be edited via the Web Admin, and some API commands called \fIsrg_\fR, for example \fIsrg_add\fR API\&. Each group has a unique name and those parameters:
Members: A list of JIDs of group members, entered one per line in the Web Admin\&. The special member directive
\fI@all@\fR
represents all the registered users in the virtual host; which is only recommended for a small server with just a few hundred users\&. The special member directive
\fI@online@\fR
represents the online users in the virtual host\&. With those two directives, the actual list of members in those shared rosters is generated dynamically at retrieval time\&.
Take the case of a computer club that wants all its members seeing each other in their rosters\&. To achieve this, they need to create a shared roster group similar to this one:
In another case we have a company which has three divisions: Management, Marketing and Sales\&. All group members should see all other members in their rosters\&. Additionally, all managers should have all marketing and sales people in their roster\&. Simultaneously, all marketeers and the whole sales team should see all managers\&. This scenario can be achieved by creating shared roster groups as shown in the following lists:
This module lets the server administrator automatically populate users\*(Aq rosters (contact lists) with entries based on users and groups defined in an LDAP\-based directory\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
\fImod_shared_roster_ldap\fR depends on \fImod_roster\fR being enabled\&. Roster queries will return \fI503\fR errors if \fImod_roster\fR is not enabled\&.
.sp.5v
.RE
.sp
The module accepts many configuration options\&. Some of them, if unspecified, default to the values specified for the top level of configuration\&. This lets you avoid specifying, for example, the bind password in multiple places\&.
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Filters:
\fIldap_rfilter\fR,
\fIldap_ufilter\fR,
\fIldap_gfilter\fR,
\fIldap_filter\fR\&. These options specify LDAP filters used to query for shared roster information\&. All of them are run against the ldap_base\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Attributes:
\fIldap_groupattr\fR,
\fIldap_groupdesc\fR,
\fIldap_memberattr\fR,
\fIldap_userdesc\fR,
\fIldap_useruid\fR\&. These options specify the names of the attributes which hold interesting data in the entries returned by running filters specified with the filter options\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Control parameters:
\fIldap_auth_check\fR,
\fIldap_group_cache_validity\fR,
\fIldap_memberattr_format\fR,
\fIldap_memberattr_format_re\fR,
\fIldap_user_cache_validity\fR\&. These parameters control the behaviour of the module\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Connection parameters: The module also accepts the connection parameters, all of which default to the top\-level parameter of the same name, if unspecified\&. See
Check also the \fIldap\&.md#ldap\-examples|Configuration examples\fR section to get details about retrieving the roster, and configuration examples including Flat DIT and Deep DIT\&.
"Group Filter", used when retrieving human\-readable name (a\&.k\&.a\&. "Display Name") and the members of a group\&. See also the parameters
\fIldap_groupattr\fR,
\fIldap_groupdesc\fR
and
\fIldap_memberattr\fR\&. If unspecified, defaults to the top\-level parameter of the same name\&. If that one also is unspecified, then the filter is constructed exactly like "User Filter"\&.
.RE
.PP
\fBldap_groupattr\fR
.RS4
The name of the attribute that holds the group name, and that is used to differentiate between them\&. Retrieved from results of the "Roster Filter" and "Group Filter"\&. Defaults to
\fIcn\fR\&.
.RE
.PP
\fBldap_groupdesc\fR
.RS4
The name of the attribute which holds the human\-readable group name in the objects you use to represent groups\&. Retrieved from results of the "Group Filter"\&. Defaults to whatever
\fIldap_groupattr\fR
is set\&.
.RE
.PP
\fBldap_memberattr\fR
.RS4
The name of the attribute which holds the IDs of the members of a group\&. Retrieved from results of the "Group Filter"\&. Defaults to
\fImemberUid\fR\&. The name of the attribute differs depending on the objectClass you use for your group objects, for example:
\fIposixGroup\fR
→
\fImemberUid\fR;
\fIgroupOfNames\fR
→
\fImember\fR;
\fIgroupOfUniqueNames\fR
→
\fIuniqueMember\fR\&.
.RE
.PP
\fBldap_memberattr_format\fR
.RS4
A globbing format for extracting user ID from the value of the attribute named by
\fIldap_memberattr\fR\&. Defaults to
\fI%u\fR, which means that the whole value is the member ID\&. If you change it to something different, you may also need to specify the User and Group Filters manually; see section Filters\&.
.RE
.PP
\fBldap_memberattr_format_re\fR
.RS4
A regex for extracting user ID from the value of the attribute named by
So called "Roster Filter"\&. Used to find names of all "shared roster" groups\&. See also the
\fIldap_groupattr\fR
parameter\&. If unspecified, defaults to the top\-level parameter of the same name\&. You must specify it in some place in the configuration, there is no default\&.
.RE
.PP
\fBldap_rootdn\fR
.RS4
Same as top\-level
\fIldap_rootdn\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_servers\fR
.RS4
Same as top\-level
\fIldap_servers\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_tls_cacertfile\fR
.RS4
Same as top\-level
\fIldap_tls_cacertfile\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_tls_certfile\fR
.RS4
Same as top\-level
\fIldap_tls_certfile\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_tls_depth\fR
.RS4
Same as top\-level
\fIldap_tls_depth\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_tls_verify\fR
.RS4
Same as top\-level
\fIldap_tls_verify\fR
option, but applied to this module only\&.
.RE
.PP
\fBldap_ufilter\fR
.RS4
"User Filter", used for retrieving the human\-readable name of roster entries (usually full names of people in the roster)\&. See also the parameters
\fIldap_userdesc\fR
and
\fIldap_useruid\fR\&. For more information check the LDAP
The name of the attribute which is used to map user id to XMPP jid\&. If not specified (and that is default value of this option), user jid will be created from user id and this module host\&.
The name of the attribute which holds the ID of a roster item\&. Value of this attribute in the roster item objects needs to match the ID retrieved from the
\fIldap_memberattr\fR
attribute of a group object\&. Retrieved from results of the "User Filter"\&. Defaults to
This module adds support for XEP\-0279: Server IP Check\&. This protocol enables a client to discover its external IP address\&.
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBWarning\fR
.ps-1
.br
.sp
The protocol extension is deferred and seems like there are no clients supporting it, so using this module is not recommended and, furthermore, the module might be removed in the future\&.
It is not enough to just load this module\&. You should also configure listeners and DNS records properly\&. For details see the section about the \fIlisten\&.md#ejabberd_sip|ejabberd_sip\fR listen module in the ejabberd Documentation\&.
Always insert "Record\-Route" header into SIP messages\&. With this approach it is possible to bypass NATs/firewalls a bit more easily\&. The default value is
is utilized, ejabberd inserts "Record\-Route" header field with this
\fIURI\fR
into a SIP message\&. The default is a SIP URI constructed from the virtual host on which the module is loaded\&.
.RE
.PP
\fBroutes\fR: \fI[URI, \&.\&.\&.]\fR
.RS4
You can set a list of SIP URIs of routes pointing to this SIP proxy server\&. The default is a list containing a single SIP URI constructed from the virtual host on which the module is loaded\&.
.RE
.PP
\fBvia\fR: \fI[URI, \&.\&.\&.]\fR
.RS4
A list to construct "Via" headers for inserting them into outgoing SIP messages\&. This is useful if you\(cqre running your SIP proxy in a non\-standard network topology\&. Every
\fIURI\fR
element in the list must be in the form of "scheme://host:port", where "transport" must be
\fItls\fR,
\fItcp\fR, or
\fIudp\fR, "host" must be a domain name or an IP address and "port" must be an internet port number\&. Note that all parts of the
\fIURI\fR
are mandatory (e\&.g\&. you cannot omit "port" or "scheme")\&.
This module adds support for XEP\-0039: Statistics Gathering\&. This protocol allows you to retrieve the following statistics from your ejabberd server:
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Total number of registered users on the current virtual host (users/total)\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Total number of registered users on all virtual hosts (users/all\-hosts/total)\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Total number of online users on the current virtual host (users/online)\&.
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Total number of online users on all virtual hosts (users/all\-hosts/online)\&.
.RE
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBNote\fR
.ps-1
.br
.sp
The protocol extension is deferred and seems like even a few clients that were supporting it are now abandoned\&. So using this module makes very little sense\&.
This module adds support for XEP\-0198: Stream Management\&. This protocol allows active management of an XML stream between two XMPP entities, including features for stanza acknowledgments and stream resumption\&.
This option specifies the maximum number of unacknowledged stanzas queued for possible retransmission\&. When the limit is exceeded, the client session is terminated\&. The allowed values are positive integers and
\fIinfinity\fR\&. You should be careful when setting this value as it should not be set too low, otherwise, you could kill sessions in a loop, before they get the chance to finish proper session initiation\&. It should definitely be set higher that the size of the offline queue (for example at least 3 times the value of the max offline queue and never lower than
\fI1000\fR)\&. The default value is
\fI5000\fR\&.
.RE
.PP
\fBmax_resume_timeout\fR: \fItimeout()\fR
.RS4
A client may specify the period of time until a session times out if the connection is lost\&. During this period of time, the client may resume its session\&. This option limits the period of time a client is permitted to request\&. It must be set to a timeout equal to or larger than the default
\fIresume_timeout\fR\&. By default, it is set to the same value as the
\fItrue\fR, any message stanzas that weren\(cqt acknowledged by the client will be resent on session timeout\&. This behavior might often be desired, but could have unexpected results under certain circumstances\&. For example, a message that was sent to two resources might get resent to one of them if the other one timed out\&. Therefore, the default value for this option is
\fIfalse\fR, which tells ejabberd to generate an error message instead\&. As an alternative, the option may be set to
\fIif_offline\fR\&. In this case, unacknowledged messages are resent only if no other resource is online when the session times out\&. Otherwise, error messages are generated\&.
.RE
.PP
\fBresume_timeout\fR: \fItimeout()\fR
.RS4
This option configures the (default) period of time until a session times out if the connection is lost\&. During this period of time, a client may resume its session\&. Note that the client may request a different timeout value, see the
\fImax_resume_timeout\fR
option\&. Setting it to
\fI0\fR
effectively disables session resumption\&. The default value is
This module allows XMPP clients to discover STUN/TURN services and to obtain temporary credentials for using them as per XEP\-0215: External Service Discovery\&.
This option defines which access rule will be used to control who is allowed to discover STUN/TURN services and to request temporary credentials\&. The default value is
\fIlocal\fR\&.
.RE
.PP
\fBcredentials_lifetime\fR: \fItimeout()\fR
.RS4
The lifetime of temporary credentials offered to clients\&. If ejabberd\(cqs built\-in TURN service is used, TURN relays allocated using temporary credentials will be terminated shortly after the credentials expired\&. The default value is
This option specifies whether local STUN/TURN services configured as ejabberd listeners should be announced automatically\&. Note that this will not include TLS\-enabled services, which must be configured manually using the
\fIservices\fR
option (see below)\&. For non\-anonymous TURN services, temporary credentials will be offered to the client\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBsecret\fR: \fIText\fR
.RS4
The secret used for generating temporary credentials\&. If this option isn\(cqt specified, a secret will be auto\-generated\&. However, a secret must be specified explicitly if non\-anonymous TURN services running on other ejabberd nodes and/or external TURN
\fIservices\fR
are configured\&. Also note that auto\-generated secrets are lost when the node is restarted, which invalidates any credentials offered before the restart\&. Therefore, it\(cqs recommended to explicitly specify a secret if clients cache retrieved credentials (for later use) across service restarts\&.
.RE
.PP
\fBservices\fR: \fI[Service, \&.\&.\&.]\fR
.RS4
The list of services offered to clients\&. This list can include STUN/TURN services running on any ejabberd node and/or external services\&. However, if any listed TURN service not running on the local ejabberd node requires authentication, a
\fIsecret\fR
must be specified explicitly, and must be shared with that service\&. This will only work with ejabberd\(cqs built\-in STUN/TURN server and with external servers that support the same
REST API For Access To TURN Services\&. Unless the
\fIoffer_local_services\fR
is set to
\fIfalse\fR, the explicitly listed services will be offered in addition to those announced automatically\&.
.PP
\fBhost\fR: \fIHost\fR
.RS4
The hostname or IP address the STUN/TURN service is listening on\&. For non\-TLS services, it\(cqs recommended to specify an IP address (to avoid additional DNS lookup latency on the client side)\&. For TLS services, the hostname (or IP address) should match the certificate\&. Specifying the
\fIhost\fR
option is mandatory\&.
.RE
.PP
\fBport\fR: \fI1\&.\&.65535\fR
.RS4
The port number the STUN/TURN service is listening on\&. The default port number is 3478 for non\-TLS services and 5349 for TLS services\&.
.RE
.PP
\fBrestricted\fR: \fItrue | false\fR
.RS4
This option determines whether temporary credentials for accessing the service are offered\&. The default is
\fIfalse\fR
for STUN/STUNS services and
\fItrue\fR
for TURN/TURNS services\&.
.RE
.PP
\fBtransport\fR: \fItcp | udp\fR
.RS4
The transport protocol supported by the service\&. The default is
This module adds support for XEP\-0202: Entity Time\&. In other words, the module reports server\(cqs system time\&.
.sp
The module has no options\&.
.SS"mod_vcard"
.sp
This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in XEP\-0054: vcard\-temp\&. The module also implements an uncomplicated Jabber User Directory based on the vCards of these users\&. Moreover, it enables the server to send its vCard when queried\&.
.sp
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.br
.ps+1
\fBAvailable options:\fR
.RS4
.PP
\fBallow_return_all\fR: \fItrue | false\fR
.RS4
This option enables you to specify if search operations with empty input fields should return all users who added some information to their vCard\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql | ldap\fR
.RS4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBhost\fR
.RS4
Deprecated\&. Use
\fIhosts\fR
instead\&.
.RE
.PP
\fBhosts\fR: \fI[Host, \&.\&.\&.]\fR
.RS4
This option defines the Jabber IDs of the service\&. If the
\fIhosts\fR
option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "vjud\&."\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&.
.RE
.PP
\fBmatches\fR: \fIpos_integer() | infinity\fR
.RS4
With this option, the number of reported search results can be limited\&. If the option\(cqs value is set to
\fIinfinity\fR, all search results are reported\&. The default value is
\fI30\fR\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS4
The value of the service name\&. This name is only visible in some clients that support
XEP\-0030: Service Discovery\&. The default is
\fIvCard User Search\fR\&.
.RE
.PP
\fBsearch\fR: \fItrue | false\fR
.RS4
This option specifies whether the search functionality is enabled or not\&. If disabled, the options
\fIhosts\fR,
\fIname\fR
and
\fIvcard\fR
will be ignored and the Jabber User Directory service will not appear in the Service Discovery item list\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.PP
\fBvcard\fR: \fIvCard\fR
.RS4
A custom vCard of the server that will be displayed by some XMPP clients in Service Discovery\&. The value of
\fIvCard\fR
is a YAML map constructed from an XML representation of vCard\&. Since the representation has no attributes, the mapping is straightforward\&.
Whether to perform search on all virtual hosts or not\&. The default value is
\fItrue\fR\&.
.RE
.RE
.SS"mod_vcard_xupdate"
.sp
The user\(cqs client can store an avatar in the user vCard\&. The vCard\-Based Avatars protocol (XEP\-0153) provides a method for clients to inform the contacts what is the avatar hash value\&. However, simple or small clients may not implement that protocol\&.
.sp
If this module is enabled, all the outgoing client presence stanzas get automatically the avatar hash on behalf of the client\&. So, the contacts receive the presence stanzas with the \fIUpdate Data\fR described in XEP\-0153 as if the client would had inserted it itself\&. If the client had already included such element in the presence stanza, it is replaced with the element generated by ejabberd\&.
.sp
By enabling this module, each vCard modification produces a hash recalculation, and each presence sent by a client produces hash retrieval and a presence stanza rewrite\&. For this reason, enabling this module will introduce a computational overhead in servers with clients that change frequently their presence\&. However, the overhead is significantly reduced by the use of caching, so you probably don\(cqt want to set \fIuse_cache\fR to \fIfalse\fR\&.
Nowadays XEP\-0153 is used mostly as "read\-only", i\&.e\&. modern clients don\(cqt publish their avatars inside vCards\&. Thus in the majority of cases the module is only used along with \fImod_avatar\fR for providing backward compatibility\&.
