EJABBERD.YML(5) EJABBERD.YML(5)
NAME
ejabberd.yml - main configuration file for ejabberd.
SYNOPSIS
ejabberd.yml
DESCRIPTION
The configuration file is written in YAML language.
Warning
YAML is indentation sensitive, so make sure you respect
indentation, or otherwise you will get pretty cryptic configuration
errors.
Logically, configuration options are split into 3 main categories:
Modules, Listeners and everything else called Top Level 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:
hosts:
- example.com
- domain.tld
loglevel: info
...
listen:
-
port: 5222
module: ejabberd_c2s
...
modules:
mod_roster: {}
...
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.
All options can be changed in runtime by running ejabberdctl
reload-config 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.
Some options can be specified for particular virtual host(s) only using
host_config or append_host_config options. Such options are called
local. Examples are modules, auth_method and default_db. The options
that cannot be defined per virtual host are called global. Examples are
loglevel, certfiles and listen. It is a configuration mistake to put
global options under host_config or append_host_config 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/26.07/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.
TOP LEVEL OPTIONS
This section describes top level options of ejabberd 26.07. The options
that changed in this version are marked with .
access_rules: {AccessName: {allow|deny: ACLName|ACLDefinition}}
This option defines basic.md#access-rules|Access Rules. Each access
rule is assigned a name that can be referenced from other parts of
the configuration file (mostly from access options of ejabberd
modules). Each rule definition may contain arbitrary number of
allow or deny sections, and each section may contain any number of
ACL rules (see acl option). There are no access rules defined by
default.
Example:
access_rules:
configure:
allow: admin
something:
deny: someone
allow: all
s2s_banned:
deny: problematic_hosts
deny: banned_forever
deny:
ip: 222.111.222.111/32
deny:
ip: 111.222.111.222/32
allow: all
xmlrpc_access:
allow:
user: peter@example.com
allow:
user: ivone@example.com
allow:
user: bot@example.com
ip: 10.0.0.0/24
acl: {ACLName: {ACLType: ACLValue}}
This option defines ../configuration/basic.md#acl|access control
lists: 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 ACLName: it can be any string except all or none
(those are predefined names for the rules that match all or nothing
respectively). The name ACLName can be referenced from other parts
of the configuration file, for example in access_rules option. The
rules of ACLName are represented by mapping {ACLType: ACLValue}.
These can be one of the following:
ip: Network
The rule matches any IP address from the Network.
node_glob: Pattern
Same as node_regexp, but matching is performed on a specified
Pattern according to the rules used by the Unix shell.
node_regexp: user_regexp@server_regexp
The rule matches any JID with node part matching regular
expression user_regexp and server part matching regular
expression server_regexp.
resource: Resource
The rule matches any JID with a resource Resource.
resource_glob: Pattern
Same as resource_regexp, but matching is performed on a
specified Pattern according to the rules used by the Unix
shell.
resource_regexp: Regexp
The rule matches any JID with a resource that matches regular
expression Regexp.
server: Server
The rule matches any JID from server Server. The value of
Server must be a valid hostname or an IP address.
server_glob: Pattern
Same as server_regexp, but matching is performed on a specified
Pattern according to the rules used by the Unix shell.
server_regexp: Regexp
The rule matches any JID from the server that matches regular
expression Regexp.
user: Username
If Username is in the form of "user@server", the rule matches a
JID against this value. Otherwise, if Username is in the form
of "user", the rule matches any JID that has Username in the
node part as long as the server part of this JID is any virtual
host served by ejabberd.
user_glob: Pattern
Same as user_regexp, but matching is performed on a specified
Pattern according to the rules used by the Unix shell.
user_regexp: Regexp
If Regexp 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
Regexp 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.
acme: Options
basic.md#acme|ACME 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 Options are:
auto: true | false
Whether to automatically request certificates for all
configured domains (that yet have no a certificate) on server
start or configuration reload. The default is true.
ca_url: URL
The ACME directory URL used as an entry point for the ACME
server. The default value is
https://acme-v02.api.letsencrypt.org/directory - the directory
URL of Let's Encrypt authority.
cert_type: rsa | ec
A type of a certificate key. Available values are ec and rsa
for EC and RSA certificates respectively. It's better to have
RSA certificates for the purpose of backward compatibility with
legacy clients and servers, thus the default is rsa.
contact: [Contact, ...]
A list of contact addresses (typically emails) where an ACME
server will send notifications when problems occur. The value
of Contact 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.
Example:
acme:
ca_url: https://acme-v02.api.letsencrypt.org/directory
contact:
- mailto:admin@domain.tld
- mailto:bot@domain.tld
auto: true
cert_type: rsa
allow_contrib_modules: true | false
Whether to allow installation of third-party modules or not. See
../../admin/guide/modules.md#ejabberd-modules|ejabberd-modules
documentation section. The default value is true.
allow_multiple_connections: true | false
This option is only used when the anonymous mode is enabled.
Setting it to true 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 false.
anonymous_protocol: login_anon | sasl_anon | both
Define what
authentication.md#anonymous-login-and-sasl-anonymous|anonymous
protocol will be used:
o login_anon means that the anonymous login method will be used.
o sasl_anon means that the SASL Anonymous method will be used.
o both means that SASL Anonymous and login anonymous are both
enabled.
The default value is sasl_anon.
api_permissions: [Permission, ...]
Define the permissions for API access. Please consult the ejabberd
Docs web -> For Developers -> ejabberd ReST API ->
../../developer/ejabberd-api/permissions.md|API Permissions.
append_host_config: {Host: Options}
Add a few specific options to a certain
../configuration/basic.md#virtual-hosting|virtual host.
auth_cache_life_time: timeout()
Same as cache_life_time, but applied to authentication cache only.
If not set, the value from cache_life_time will be used.
auth_cache_missed: true | false
Same as cache_missed, but applied to authentication cache only. If
not set, the value from cache_missed will be used.
auth_cache_size: pos_integer() | infinity
Same as cache_size, but applied to authentication cache only. If
not set, the value from cache_size will be used.
auth_external_user_exists_check: true | false
Note about this option: added in 23.10. Supplement check for user
existence based on mod_last data, for authentication methods that
don't have a way to reliably tell if a user exists (like is the
case for jwt and certificate based authentication). This helps with
processing offline message for those users. The default value is
true.
auth_method: [mnesia | sql | anonymous | external | jwt | ldap | pam,
...]
A list of authentication.md|authentication 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 [mnesia].
auth_opts: [Option, ...]
This is used by the contributed module ejabberd_auth_http that can
be installed from the
../../admin/guide/modules.md#ejabberd-contrib|ejabberd-contrib Git
repository. Please refer to that module's README file for details.
auth_password_format: plain | scram
Note about this option: improved in 20.01. The option defines in
what format the users passwords are stored, plain text or in
authentication.md#scram|SCRAM format:
o plain: 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).
o scram: 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
auth_scram_hash option.
The default value is plain.
auth_password_types_hidden_in_sasl1: [plain | scram_sha1 | scram_sha256
| scram_sha512]
Note about this option: added in 25.07. List of password types that
should not be offered in SASL1 authenticatication. Because SASL1,
unlike SASL2, can't have list of available mechanisms tailored to
individual user, it's possible that offered mechanisms will not be
compatible with stored password, especially if new password type
was added recently. This option allows disabling offering some
mechanisms in SASL1, to a time until new password type will be
available for all users.
auth_scram_hash: sha | sha256 | sha512
Hash algorithm that should be used to store password in
authentication.md#scram|SCRAM format. You shouldn't 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 sha.
auth_stored_password_types: [plain | scram_sha1 | scram_sha256 |
scram_sha512]
Note about this option: added in 25.03. List of password types that
should be stored simultaneously for each user in database. When the
user sets the account password, database will be updated to store
the password in formats compatible with each type listed here. This
can be used to migrate user passwords to a more secure format. If
this option if set, it will override values set in auth_scram_hash
and auth_password_format options. The default value is [].
auth_use_cache: true | false
Same as use_cache, but applied to authentication cache only. If not
set, the value from use_cache will be used.
c2s_cafile: Path
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
subjectAltName field. There is no default value.
You can use host_config to specify this option per-vhost.
To set a specific file per listener, use the listener's
listen-options.md#cafile|cafile option. Please notice that c2s_cafile
overrides the listener's cafile option.
c2s_ciphers: [Cipher, ...]
A list of OpenSSL ciphers to use for c2s connections. The default
value is shown in the example below:
Example:
c2s_ciphers:
- HIGH
- "!aNULL"
- "!eNULL"
- "!3DES"
- "@STRENGTH"
c2s_dhfile: Path
Full path to a file containing custom DH parameters to use for c2s
connections. Such a file could be created with the command "openssl
dhparam -out dh.pem 2048". 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.
c2s_protocol_options: [Option, ...]
List of general SSL options to use for c2s connections. These map
to OpenSSL's set_options(). The default value is shown in the
example below:
Example:
c2s_protocol_options:
- no_sslv3
- cipher_server_preference
- no_compression
c2s_tls_compression: true | false
Whether to enable or disable TLS compression for c2s connections.
The default value is false.
ca_file: Path
Path to a file of CA root certificates. The default is to use
system defined file if possible.
For server connections, this ca_file option is overridden by the
s2s_cafile option.
cache_life_time: timeout()
The time of a cached item to keep in cache. Once it's expired, the
corresponding item is erased from cache. The default value is 1
hour. Several modules have a similar option; and some core ejabberd
parts support similar options too, see auth_cache_life_time,
oauth_cache_life_time, router_cache_life_time, and
sm_cache_life_time.
cache_missed: true | false
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 true, this attempt will be cached and no
attempts will be performed until the cache expires (see
cache_life_time). Usually you don't want to change it. Default is
true. Several modules have a similar option; and some core ejabberd
parts support similar options too, see auth_cache_missed,
oauth_cache_missed, router_cache_missed, and sm_cache_missed.
cache_size: pos_integer() | infinity
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's
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 1000.
Several modules have a similar option; and some core ejabberd parts
support similar options too, see auth_cache_size, oauth_cache_size,
router_cache_size, and sm_cache_size.
captcha_cmd: Path | ModuleName
Note about this option: improved in 23.01. Full path to a script
that generates basic.md#captcha|CAPTCHA images. The keyword
@VERSION@ is replaced with ejabberd version number in XX.YY format.
The keyword @SEMVER@ is replaced with ejabberd version number in
semver format when compiled with Elixir's 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.
Examples:
When using the ejabberd installers or container image, the example
captcha scripts can be used like this:
captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh
captcha_host: String
Deprecated. Use captcha_url instead.
captcha_limit: pos_integer() | infinity
Maximum number of basic.md#captcha|CAPTCHA generated images per
minute for any given JID. The option is intended to protect the
server from CAPTCHA DoS. The default value is infinity.
captcha_url: URL | auto | undefined
Note about this option: improved in 23.04. An URL where
basic.md#captcha|CAPTCHA requests should be sent. NOTE: you need to
configure request_handlers for ejabberd_http listener as well. If
set to auto, it builds the URL using a request_handler already
enabled, with encryption if available. If set to undefined, it
builds the URL using the deprecated captcha_host + /captcha. The
default value is auto.
certfiles: [Path, ...]
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: ejabberd_c2s, ejabberd_http and so on. NOTE: if
you modify the certificate files or change the value of the option,
run ejabberdctl reload-config in order to rebuild and reload the
certificate chains.
Examples:
If you use Let's Encrypt certificates for your domain "domain.tld",
the configuration will look like this:
certfiles:
- /etc/letsencrypt/live/domain.tld/fullchain.pem
- /etc/letsencrypt/live/domain.tld/privkey.pem
cluster_backend: Backend
A database backend to use for storing information about cluster.
The only available value so far is mnesia.
cluster_nodes: [Node, ...]
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_db: mnesia | sql
database.md#default-database|Default database to store persistent
data in ejabberd. Some components can be configured with specific
toplevel options like oauth_db_type. Many modules can be configured
with specific module options, usually named db_type. The default
value is mnesia.
default_ram_db: mnesia | redis | sql
Default volatile (in-memory) storage for ejabberd. Some components
can be configured with specific toplevel options like
router_db_type and sm_db_type. Some modules can be configured with
specific module options, usually named ram_db_type. The default
value is mnesia.
define_keyword: {NAME: Value}
Note about this option: added in 25.03. Allows to define
configuration
../configuration/file-format.md#macros-and-keywords|keywords.
Example:
define_keyword:
SQL_USERNAME: "eja.global"
host_config:
localhost:
define_keyword:
SQL_USERNAME: "eja.localhost"
sql_username: "prefix.@SQL_USERNAME@"
define_macro: {NAME: Value}
Note about this option: improved in 25.03. Allows to define
configuration
../configuration/file-format.md#macros-and-keywords|macros.
Example:
define_macro:
DEBUG: debug
LOG_LEVEL: DEBUG
USERBOB:
user: bob@localhost
loglevel: LOG_LEVEL
acl:
admin: USERBOB
disable_sasl_mechanisms: [Mechanism, ...]
Specify a list of SASL mechanisms (such as DIGEST-MD5 or
SCRAM-SHA1) that should not be offered to the client. For
convenience, the value of Mechanism is case-insensitive. The
default value is an empty list, i.e. no mechanisms are disabled by
default.
disable_sasl_scram_downgrade_protection: true | false
Allows to disable sending data required by XEP-0474: SASL SCRAM
Downgrade Protection. 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 false which enables this extension.
domain_balancing: {Domain: Options}
An algorithm to
../guide/clustering.md#service-load-balancing|load-balance 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
Domain, available Options are:
component_number: 2..1000
The number of components to balance.
type: Value
How to deliver stanzas to connected components. The default
value is random. Possible values:
- bare_destination
by the bare JID (without resource) of the packet's to attribute
- bare_source
by the bare JID (without resource) of the packet's from
attribute is used
- destination
an instance is chosen by the full JID of the packet's to
attribute
- random
an instance is chosen at random
- source
by the full JID of the packet's from attribute
Example:
domain_balancing:
component.domain.tld:
type: destination
component_number: 5
transport.example.org:
type: bare_source
ext_api_headers: Headers
String of headers (separated with commas ,) that will be provided
by ejabberd when sending ReST requests. The default value is an
empty string of headers: "".
ext_api_http_pool_size: pos_integer()
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: 100.
ext_api_path_oauth: Path
Define the base URI path when performing OAUTH ReST requests. The
default value is: "/oauth".
ext_api_url: URL
Define the base URI when performing ReST requests. The default
value is: "http://localhost/api".
extauth_pool_name: Name
Define the pool name appendix in
authentication.md#external-script|external auth, so the full pool
name will be extauth_pool_Name. The default value is the hostname.
extauth_pool_size: Size
The option defines the number of instances of the same
authentication.md#external-script|external auth program to start
for better load balancing. The default is the number of available
CPU cores.
extauth_program: Path
Indicate in this option the full path to the
authentication.md#external-script|external authentication script.
The script must be executable by ejabberd.
fqdn: Domain
A fully qualified domain name that will be used in SASL DIGEST-MD5
authentication. The default is detected automatically.
hide_sensitive_log_data: true | false
A privacy option to not log sensitive data (mostly IP addresses).
The default value is false for backward compatibility.
host_config: {Host: Options}
The option is used to redefine Options for
../configuration/basic.md#virtual-hosting|virtual host Host. In the
example below LDAP authentication method will be used on virtual
host domain.tld and SQL method will be used on virtual host
example.org.
Example:
hosts:
- domain.tld
- example.org
auth_method:
- sql
host_config:
domain.tld:
auth_method:
- ldap
hosts: [Domain1, Domain2, ...]
List of one or more ../configuration/basic.md#host-names|host names
(or domains) that ejabberd will serve. This is a mandatory option.
hosts_alias: {Alias: Host}
Note about this option: added in 25.07. Define aliases for existing
vhosts managed by ejabberd. An alias may be a regexp expression.
This option is only consulted by the ejabberd_http listener.
Example:
hosts:
- domain.tld
- example.org
hosts_alias:
xmpp.domain.tld: domain.tld
jabber.domain.tld: domain.tld
mytest.net: example.org
"exa*": example.org
include_config_file: [Filename, ...] | {Filename: Options}
Read and
../configuration/file-format.md#include-additional-files|include
additional file from Filename. If the value is provided in
{Filename: Options} format, the Options must be one of the
following:
allow_only: [OptionName, ...]
Allows only the usage of those options in the included file
Filename. The options that do not match this criteria are not
accepted. The default value is to include all options.
disallow: [OptionName, ...]
Disallows the usage of those options in the included file
Filename. The options that match this criteria are not
accepted. The default value is an empty list.
install_contrib_modules: [Module, ...]
Note about this option: added in 23.10. Modules from
../../admin/guide/modules.md#ejabberd-modules|ejabberd-modules to
install automatically at start time. The default value is an empty
list of modules: [].
Example:
install_contrib_modules:
- mod_tombstones
modules:
mod_tombstones: {}
jwt_auth_only_rule: AccessName
This ACL rule defines accounts that can use only the
authentication.md#jwt-authentication|JWT 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 none.
jwt_jid_field: FieldName
By default, the JID is defined in the "jid" JWT field. In this
option you can specify other
authentication.md#jwt-authentication|JWT field name where the JID
is defined.
jwt_key: FilePath
Path to the file that contains the
authentication.md#jwt-authentication|JWT key.
Supported file formats:
o PEM format - Standard PEM-encoded keys (RSA, EC, EdDSA, etc.)
o JWK (JSON Web Key) - JSON format
o JWK Set - JSON with a "keys" array (but must contain exactly one
key)
By default there is no path defined, that is: undefined.
language: Language
Define the ../configuration/basic.md#default-language|default
language of server strings that can be seen by XMPP clients. If an
XMPP client does not possess xml:lang attribute, the specified
language is used. The default value is "en".
ldap_backups: [Host, ...]
A list of IP addresses or DNS names of LDAP backup servers (see
../configuration/ldap.md#ldap-connection|LDAP connection). When no
servers listed in ldap_servers 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't detect when a previously-attempted server becomes
available again.
ldap_base: Base
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.
ldap_deref_aliases: never | always | finding | searching
Whether to dereference aliases or not. The default value is never.
ldap_dn_filter: {Filter: FilterAttrs}
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 ldap_filter. You can define "%u", "%d", "%s" and "%D"
pattern variables in Filter: "%u" is replaced by a user's 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 FilterAttrs 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 ldap_filter option if possible.
Example:
ldap_dn_filter:
"(&(name=%s)(owner=%D)(user=%u@%d))": [sn]
ldap_encrypt: tls | none
Whether to encrypt LDAP connection using TLS or not. The default
value is none. NOTE: STARTTLS encryption is not supported.
ldap_filter: Filter
An LDAP filter as defined in RFC4515. There is no default value.
Example: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))".
NOTE: don't forget to close brackets and don't use superfluous
whitespaces. Also you must not use "uid" attribute in the filter
because this attribute will be appended to the filter
automatically.
ldap_password: Password
Bind password. The default value is an empty string.
ldap_port: 1..65535
Port to connect to your LDAP server. The default port is 389 if
encryption is disabled and 636 if encryption is enabled.
ldap_rootdn: RootDN
Bind Distinguished Name. The default value is an empty string,
which means "anonymous connection".
ldap_servers: [Host, ...]
A list of IP addresses or DNS names of your LDAP servers (see
../configuration/ldap.md#ldap-connection|LDAP connection). ejabberd
connects immediately to all of them, and reconnects infinitely if
connection is lost. The default value is [localhost].
ldap_tls_cacertfile: Path
A path to a file containing PEM encoded CA certificates. This
option is required when TLS verification is enabled.
ldap_tls_certfile: Path
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.
ldap_tls_depth: Number
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 2 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 1.
ldap_tls_verify: false | soft | hard
This option specifies whether to verify LDAP server certificate or
not when TLS is enabled. When hard is set, ejabberd doesn't proceed
if the certificate is invalid. When soft is set, ejabberd proceeds
even if the check has failed. The default is false, which means no
checks are performed.
ldap_uids: [Attr] | {Attr: AttrFormat}
LDAP attributes which hold a list of attributes to use as
alternatives for getting the JID, where Attr is an LDAP attribute
which holds the user's part of the JID and AttrFormat must contain
one and only one pattern variable "%u" which will be replaced by
the user's part of the JID. For example, "%u@example.org". If the
value is in the form of [Attr] then AttrFormat is assumed to be
"%u".
listen: [Options, ...]
The option for listeners configuration. See the listen.md|Listen
Modules section for details.
log_burst_limit_count: Number
Note about this option: added in 22.10. The number of messages to
accept in log_burst_limit_window_time period before starting to
drop them. Default 500
log_burst_limit_window_time: Number
Note about this option: added in 22.10. The time period to
rate-limit log messages by. Defaults to 1 second.
log_modules_fully: [Module, ...]
Note about this option: added in 23.01. List of modules that will
log everything independently from the general loglevel option.
log_rotate_count: Number
The number of rotated log files to keep. The default value is 1,
which means that only keeps ejabberd.log.0, error.log.0 and
crash.log.0.
log_rotate_size: pos_integer() | infinity
The size (in bytes) of a log file to trigger rotation. If set to
infinity, log rotation is disabled. The default value is 10 Mb
expressed in bytes: 10485760.
loglevel: none | emergency | alert | critical | error | warning |
notice | info | debug
Verbosity of ejabberd ../configuration/basic.md#logging|logging.
The default value is info. NOTE: previous versions of ejabberd had
log levels defined in numeric format (0..5). The numeric values are
still accepted for backward compatibility, but are not recommended.
max_fsm_queue: Size
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 10000.
modules: {Module: Options}
Set all the modules.md|modules configuration options.
negotiation_timeout: timeout()
Time to wait for an XMPP stream negotiation to complete. When
timeout occurs, the corresponding XMPP stream is closed. The
default value is 120 seconds.
net_ticktime: timeout()
This option can be used to tune tick time parameter of net_kernel.
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 1 minute.
new_sql_schema: true | false
Note about this option: obsoleted in 25.10. This option was renamed
to sql_schema_multihost in ejabberd 25.10. Please update your
configuration to use the new option name
oauth_access: AccessName
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 oauth_access option. Use all to allow everyone to
create tokens.
oauth_cache_life_time: timeout()
Same as cache_life_time, but applied to OAuth cache only. If not
set, the value from cache_life_time will be used.
oauth_cache_missed: true | false
Same as cache_missed, but applied to OAuth cache only. If not set,
the value from cache_missed will be used.
oauth_cache_rest_failure_life_time: timeout()
Note about this option: added in 21.01. The time that a failure in
OAuth ReST is cached. The default value is infinity.
oauth_cache_size: pos_integer() | infinity
Same as cache_size, but applied to OAuth cache only. If not set,
the value from cache_size will be used.
oauth_client_id_check: allow | db | deny
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 db.
oauth_db_type: mnesia | sql
Database backend to use for OAuth authentication. The default value
is picked from default_db option, or if it's not set, mnesia will
be used.
oauth_expire: timeout()
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
4294967 seconds.
oauth_use_cache: true | false
Same as use_cache, but applied to OAuth cache only. If not set, the
value from use_cache will be used.
oom_killer: true | false
Enable or disable OOM (out-of-memory) killer. When system memory
raises above the limit defined in oom_watermark 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
true.
oom_queue: Size
Trigger OOM killer when some of the running Erlang processes have
messages queue above this Size. Note that such processes won't be
killed if oom_killer option is set to false or if oom_watermark is
not reached yet.
oom_watermark: Percent
A percent of total system memory consumed at which OOM killer
should be activated with some of the processes possibly be killed
(see oom_killer option). Later, when memory drops below this
Percent, OOM killer is deactivated. The default value is 80
percents.
outgoing_s2s_families: [ipv6 | ipv4, ...]
Note about this option: changed in 23.01. Specify which address
families to try, in what order. The default is [ipv6, ipv4] 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.
outgoing_s2s_ipv4_address: Address
Note about this option: added in 20.12. Specify the IPv4 address
that will be used when establishing an outgoing S2S IPv4
connection, for example "127.0.0.1". The default value is
undefined.
outgoing_s2s_ipv6_address: Address
Note about this option: added in 20.12. Specify the IPv6 address
that will be used when establishing an outgoing S2S IPv6
connection, for example "::FFFF:127.0.0.1". The default value is
undefined.
outgoing_s2s_port: 1..65535
A port number to use for outgoing s2s connections when the target
server doesn't have an SRV record. The default value is 5269.
outgoing_s2s_timeout: timeout()
The timeout in seconds for outgoing S2S connection attempts. The
default value is 10 seconds.
pam_service: Name
This option defines the authentication.md#pam-authentication|PAM
service name. Refer to the PAM documentation of your operation
system for more information. The default value is ejabberd.
pam_userinfotype: username | jid
This option defines what type of information about the user
ejabberd provides to the authentication.md#pam-authentication|PAM
service: only the username, or the user's JID. Default is username.
pgsql_users_number_estimate: true | false
Whether to use PostgreSQL estimation when counting registered
users. The default value is false.
queue_dir: Directory
If queue_type option is set to file, use this Directory to store
file queues. The default is to keep queues inside Mnesia directory.
queue_type: ram | file
Default type of queues in ejabberd. Modules may have its own value
of the option. The value of ram means that queues will be kept in
memory. If value file is set, you may also specify directory in
queue_dir option where file queues will be placed. The default
value is ram.
redis_connect_timeout: timeout()
A timeout to wait for the connection to be re-established to the
database.md#redis|Redis server. The default is 1 second.
redis_db: Number
database.md#redis|Redis database number. The default is 0.
redis_password: Password
The password to the database.md#redis|Redis server. The default is
an empty string, i.e. no password.
redis_pool_size: Number
The number of simultaneous connections to the
database.md#redis|Redis server. The default value is 10.
redis_port: 1..65535
The port where the database.md#redis|Redis server is accepting
connections. The default is 6379.
redis_queue_type: ram | file
The type of request queue for the database.md#redis|Redis server.
See description of queue_type option for the explanation. The
default value is the value defined in queue_type or ram if the
latter is not set.
redis_server: Host | IP Address | Unix Socket Path
Note about this option: improved in 24.12. A hostname, IP address
or unix domain socket file of the database.md#redis|Redis server.
Setup the path to unix domain socket like: "unix:/path/to/socket".
The default value is localhost.
registration_timeout: timeout()
This is a global option for module mod_register. 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 infinity. The default value is 600
seconds.
replaced_connection_timeout: timeout()
Note about this option: added in 26.01. Maximum time that new
session will wait for termination of session that it's replacing.
This allows old session to properly sends its unavailable
presences, and helps with potetnial race conditions between old and
new sessions presences.
resource_conflict: setresource | closeold | closenew
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 closeold. If the client uses old Jabber Non-SASL
authentication (XEP-0078), then this option is not respected, and
the action performed is closeold.
rest_proxy: Host
Note about this option: added in 25.07. Address of a HTTP Connect
proxy used by modules issuing rest calls (like ejabberd_oauth_rest)
rest_proxy_password: string()
Note about this option: added in 25.07. Password used to
authenticate to HTTP Connect proxy used by modules issuing rest
calls (like ejabberd_oauth_rest)
rest_proxy_port: 1..65535
Note about this option: added in 25.07. Port of a HTTP Connect
proxy used by modules issuing rest calls (like ejabberd_oauth_rest)
rest_proxy_username: string()
Note about this option: added in 25.07. Username used to
authenticate to HTTP Connect proxy used by modules issuing rest
calls (like ejabberd_oauth_rest)
router_cache_life_time: timeout()
Same as cache_life_time, but applied to routing table cache only.
If not set, the value from cache_life_time will be used.
router_cache_missed: true | false
Same as cache_missed, but applied to routing table cache only. If
not set, the value from cache_missed will be used.
router_cache_size: pos_integer() | infinity
Same as cache_size, but applied to routing table cache only. If not
set, the value from cache_size will be used.
router_db_type: mnesia | redis | sql
Database backend to use for routing information. The default value
is picked from default_ram_db option, or if it's not set, mnesia
will be used.
router_use_cache: true | false
Same as use_cache, but applied to routing table cache only. If not
set, the value from use_cache will be used.
rpc_timeout: timeout()
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 5
seconds.
s2s_access: Access
This basic.md#access-rules|Access Rule defines to what remote
servers can s2s connections be established. The default value is
all; no restrictions are applied, it is allowed to connect s2s
to/from all remote servers.
s2s_cafile: Path
A path to a file with CA root certificates that will be used to
authenticate s2s connections. If not set, the value of ca_file will
be used.
You can use host_config to specify this option per-vhost.
s2s_ciphers: [Cipher, ...]
A list of OpenSSL ciphers to use for s2s connections. The default
value is shown in the example below:
Example:
s2s_ciphers:
- HIGH
- "!aNULL"
- "!eNULL"
- "!3DES"
- "@STRENGTH"
s2s_dhfile: Path
Full path to a file containing custom DH parameters to use for s2s
connections. Such a file could be created with the command "openssl
dhparam -out dh.pem 2048". 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.
s2s_dns_retries: Number
DNS resolving retries. The default value is 2.
s2s_dns_timeout: timeout()
The timeout for DNS resolving. The default value is 10 seconds.
s2s_max_retry_delay: timeout()
The maximum allowed delay for s2s connection retry to connect after
a failed connection attempt. The default value is 300 seconds (5
minutes).
s2s_protocol_options: [Option, ...]
List of general SSL options to use for s2s connections. These map
to OpenSSL's set_options(). The default value is shown in the
example below:
Example:
s2s_protocol_options:
- no_sslv3
- cipher_server_preference
- no_compression
s2s_queue_type: ram | file
The type of a queue for s2s packets. See description of queue_type
option for the explanation. The default value is the value defined
in queue_type or ram if the latter is not set.
s2s_timeout: timeout()
A time to wait before closing an idle s2s connection. The default
value is 1 hour.
s2s_tls_compression: true | false
Whether to enable or disable TLS compression for s2s connections.
The default value is false.
s2s_use_starttls: true | false | optional | required
Whether to use STARTTLS for s2s connections. The value of false
means STARTTLS is prohibited. The value of true or optional means
STARTTLS is enabled but plain connections are still allowed. And
the value of required means that only STARTTLS connections are
allowed. The default value is false (for historical reasons).
s2s_zlib: true | false
Whether to use zlib compression (as defined in XEP-0138) or not.
The default value is false. WARNING: this type of compression is
nowadays considered insecure.
shaper: {ShaperName: Rate}
The option defines a set of
../configuration/basic.md#shapers|shapers. Every shaper is assigned
a name ShaperName that can be used in other parts of the
configuration file, such as shaper_rules option. The shaper itself
is defined by its Rate, where Rate stands for the maximum allowed
incoming rate in bytes 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 normal limits the traffic speed to 1,000 bytes/sec and
shaper fast limits the traffic speed to 50,000 bytes/sec:
Example:
shaper:
normal: 1000
fast: 50000
shaper_rules: {ShaperRuleName: {Number|ShaperName:
ACLName|ACLDefinition}}
This option defines ../configuration/basic.md#shaper-rules|shaper
rules to use for matching user/hosts. Semantics is similar to
access_rules option, the only difference is that instead using
allow or deny, a name of a shaper (defined in shaper option) or a
positive number should be used.
Example:
shaper_rules:
connections_limit:
10:
user: peter@example.com
100: admin
5: all
download_speed:
fast: admin
slow: anonymous_users
normal: all
log_days: 30
sm_cache_life_time: timeout()
Same as cache_life_time, but applied to client sessions table cache
only. If not set, the value from cache_life_time will be used.
sm_cache_missed: true | false
Same as cache_missed, but applied to client sessions table cache
only. If not set, the value from cache_missed will be used.
sm_cache_size: pos_integer() | infinity
Same as cache_size, but applied to client sessions table cache
only. If not set, the value from cache_size will be used.
sm_db_type: mnesia | redis | sql
Database backend to use for client sessions information. The
default value is picked from default_ram_db option, or if it's not
set, mnesia will be used.
sm_use_cache: true | false
Same as use_cache, but applied to client sessions table cache only.
If not set, the value from use_cache will be used.
sql_connect_timeout: timeout()
A time to wait for connection to an SQL server to be established.
The default value is 5 seconds.
sql_database: DatabaseName | PathSqliteFile
Note about this option: improved in 26.04. An SQL database name,
being the default value ejabberd. If option sql_type is set to
sqlite, this must be a full path to a database file, being the
default value: '"@DATABASE_PATH@/sqlite/@HOST@.sqlite"
sql_flags: [mysql_alternative_upsert]
Note about this option: added in 24.02. This option accepts a list
of SQL flags, and is empty by default. mysql_alternative_upsert
forces the alternative upsert implementation in MySQL.
sql_keepalive_interval: timeout()
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.
sql_odbc_driver: Path
Note about this option: added in 20.12. Path to the ODBC driver to
use to connect to a Microsoft SQL Server database. This option only
applies if the sql_type option is set to mssql and sql_server is
not an ODBC connection string. The default value is: libtdsodbc.so
sql_password: Password
The password for SQL authentication. The default is empty string.
sql_pool_size: Size
Number of connections to the SQL server that ejabberd will open for
each virtual host. The default value is 10. WARNING: for SQLite
this value is 1 by default and it's not recommended to change it
due to potential race conditions.
sql_port: 1..65535
The port where the SQL server is accepting connections. The default
is 3306 for MySQL, 5432 for PostgreSQL and 1433 for MS SQL. The
option has no effect for SQLite.
sql_prepared_statements: true | false
Note about this option: added in 20.01. This option is true by
default, and is useful to disable prepared statements. The option
is valid for PostgreSQL and MySQL.
sql_query_timeout: timeout()
A time to wait for an SQL query response. The default value is 60
seconds.
sql_queue_type: ram | file
The type of a request queue for the SQL server. See description of
queue_type option for the explanation. The default value is the
value defined in queue_type or ram if the latter is not set.
sql_schema_multihost: true | false
Note about this option: renamed in 25.10. Whether to use the
database.md#singlehost-or-multihost|multihost SQL schema. All
schemas are located at
https://github.com/processone/ejabberd/tree/26.07/sql. There are
two schemas available. The legacy singlehost schema stores one XMPP
domain into one ejabberd database. The multihost schema can handle
several XMPP domains in a single ejabberd database. The multihost
schema is preferable 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
../../admin/install/source.md#configure|./configure flag
--enable-sql-schema-multihost which is set at compile time.
sql_server: Host | IP Address | ODBC Connection String | Unix Socket
Path
Note about this option: improved in 24.06. The hostname or IP
address of the SQL server. For sql_type mssql or odbc this can also
be an ODBC connection string. When sql_type is mysql or pgsql, this
can be the path to a unix domain socket expressed like:
"unix:/path/to/socket".The default value is localhost.
sql_ssl: true | false
Note 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
false.
sql_ssl_cafile: Path
A path to a file with CA root certificates that will be used to
verify SQL connections. Implies sql_ssl and sql_ssl_verify options
are set to true. There is no default which means certificate
verification is disabled. This option has no effect for MS SQL.
sql_ssl_certfile: Path
A path to a certificate file that will be used for SSL connections
to the SQL server. Implies sql_ssl option is set to true. There is
no default which means ejabberd won't provide a client certificate
to the SQL server. This option has no effect for MS SQL.
sql_ssl_verify: true | false
Whether to verify SSL connection to the SQL server against CA root
certificates defined in sql_ssl_cafile option. Implies sql_ssl
option is set to true. This option has no effect for MS SQL. The
default value is false.
sql_start_interval: timeout()
A time to wait before retrying to restore failed SQL connection.
The default value is 30 seconds.
sql_type: mssql | mysql | odbc | pgsql | sqlite
The type of an SQL connection. The default is odbc.
sql_username: Username
A user name for SQL authentication. The default value is ejabberd.
trusted_proxies: all | [Network1, Network2, ...]
Specify what proxies are trusted when an HTTP request contains the
header X-Forwarded-For. You can specify all 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 mod_fail2ban). IMPORTANT: The proxy MUST be configured to set
the X-Forwarded-For 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.
update_sql_schema: true | false
Note 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 true.
update_sql_schema_timeout: timeout()
Note about this option: added in 24.07. Time allocated to SQL
schema update queries. The default value is set to 5 minutes.
use_cache: true | false
Enable or disable cache. The default is true. Several modules have
a similar option; and some core ejabberd parts support similar
options too, see auth_use_cache, oauth_use_cache, router_use_cache,
and sm_use_cache.
validate_stream: true | false
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't enable it in
production environment. The default value is false.
version: string()
The option can be used to set custom ejabberd version, that will be
used by different parts of ejabberd, for example by mod_version
module. The default value is obtained at compile time from the
underlying version control system.
websocket_origin: ignore | URL
This option enables validation for Origin 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 ignore. An example value
of the URL is "https://test.example.org:8081".
websocket_ping_interval: timeout()
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't respond to two consecutive
pings, the connection will be assumed as closed. The value of 0 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 60 seconds.
websocket_timeout: timeout()
Amount of time without any communication after which the connection
would be closed. The default value is 300 seconds.
MODULES
This section describes modules options of ejabberd 26.07. The modules
that changed in this version are marked with .
mod_adhoc
def:ad-hoc command
: Command that can be executed by an XMPP client using XEP-0050.
This module implements XEP-0050: Ad-Hoc Commands. It's an auxiliary
module and is only needed by some of the other modules.
Available options:
report_commands_node: true | false
Provide the Commands item in the Service Discovery. Default
value: false.
mod_adhoc_api
Note about this option: added in 25.03.
Execute (def:API commands) in a XMPP client using XEP-0050: Ad-Hoc
Commands. This module requires mod_adhoc (to execute the commands), and
recommends mod_disco (to discover the commands).
Available options:
default_version: integer() | string()
What API version to use. If setting an ejabberd version, it
will use the latest API version that was available in that
(def:c2s) ejabberd version. For example, setting "24.06" in
this option implies 2. The default value is the latest version.
Example:
acl:
admin:
user: jan@localhost
api_permissions:
"adhoc commands":
from: mod_adhoc_api
who: admin
what:
- "[tag:roster]"
- "[tag:session]"
- stats
- status
modules:
mod_adhoc_api:
default_version: 2
mod_admin_extra
This module provides additional administrative commands.
Details for some commands:
ban_account 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't 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.
push_roster API (and push_roster_all 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.
srg_create API: If you want to put a group Name with blank spaces, use
the characters "' and '" to define when the Name starts and ends. See
an example below.
The module has no options.
Examples:
With this configuration, vCards can only be modified with
mod_admin_extra commands:
acl:
adminextraresource:
- resource: "modadminextraf8x,31ad"
access_rules:
vcard_set:
- allow: adminextraresource
modules:
mod_admin_extra: {}
mod_vcard:
access_set: vcard_set
Content of roster file for push_roster API:
[{<<"bob">>, <<"example.org">>, <<"workers">>, <<"Bob">>},
{<<"mart">>, <<"example.org">>, <<"workers">>, <<"Mart">>},
{<<"Rich">>, <<"example.org">>, <<"bosses">>, <<"Rich">>}].
With this call, the sessions of the local account which JID is
boby@example.org will be kicked, and its password will be set to
something like
BANNED_ACCOUNT--20080425T21:45:07--2176635--Spammed_rooms
ejabberdctl vhost example.org ban_account boby "Spammed rooms"
Call to srg_create API using double-quotes and single-quotes:
ejabberdctl srg_create g1 example.org "'Group number 1'" this_is_g1 g1
API Tags:
../../developer/ejabberd-api/admin-tags.md#accounts|accounts,
../../developer/ejabberd-api/admin-tags.md#erlang|erlang,
../../developer/ejabberd-api/admin-tags.md#last|last,
../../developer/ejabberd-api/admin-tags.md#private|private,
../../developer/ejabberd-api/admin-tags.md#purge|purge,
../../developer/ejabberd-api/admin-tags.md#roster|roster,
../../developer/ejabberd-api/admin-tags.md#session|session,
../../developer/ejabberd-api/admin-tags.md#shared_roster_group|shared_roster_group,
../../developer/ejabberd-api/admin-tags.md#stanza|stanza,
../../developer/ejabberd-api/admin-tags.md#statistics|statistics,
../../developer/ejabberd-api/admin-tags.md#vcard|vcard
mod_admin_update_sql
This module can be used to convert your existing SQL database from the
singlehost to the multihost schema. Check the section
database.md#singlehost-or-multihost|Singlehost or Multihost for
details. Please note that only MS SQL, MySQL, and PostgreSQL are
supported. When the module is loaded use update_sql API.
The module has no options.
mod_announce
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. Equivalent API commands are also available.
Note
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.
To send announcements using XEP-0050: Ad-Hoc Commands, this module
requires mod_adhoc (to execute the commands), and recommends mod_disco
(to discover the commands).
To send announcements by sending messages to specific JIDs, these are
the destination JIDs:
o example.org/announce/all: Send the message to all registered users
in that vhost. 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
is stored offline in assumption that offline storage (see
mod_offline) is enabled.
o example.org/announce/online: Send the message to all connected
users. If the user is online and connected to several resources,
all resources will receive the message.
o example.org/announce/motd: Set the message of the day (MOTD) that
is sent to users when they login. Also sends the message to all
connected users (similar to announce/online).
o example.org/announce/motd/update: Set the message of the day (MOTD)
that is sent to users when they login. This does not send the
message to any currently connected user.
o example.org/announce/motd/delete: Remove the existing message of
the day (MOTD) by sending a message to this JID.
There are similar destination JIDs to apply to all virtual hosts in
ejabberd:
o example.org/announce/all-hosts/all: send to all registered accounts
o example.org/announce/all-hosts/online: send to online sessions
o example.org/announce/all-hosts/motd: set MOTD and send to online
o example.org/announce/all-hosts/motd/update: update MOTD
o example.org/announce/all-hosts/motd/delete: delete MOTD
Available options:
access: AccessName
This option specifies who is allowed to send announcements and
to set the message of the day. The default value is none (i.e.
nobody is able to send such messages).
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
API Tags:
../../developer/ejabberd-api/admin-tags.md#announce|announce
mod_antispam
Note about this option: added in 25.07.
Filter spam messages and subscription requests received from remote
servers based on Real-Time Block Lists (RTBL), lists of known spammer
JIDs and/or URLs mentioned in spam messages. Traffic classified as spam
is rejected with an error (and an [info] message is logged) unless the
sender is subscribed to the recipient's presence.
Available options:
access_spam: Access
Access rule that controls what accounts may receive spam
messages. If the rule returns allow for a given recipient, spam
messages aren't rejected for that recipient. The default value
is none, which means that all recipients are subject to spam
filtering verification.
cache_size: pos_integer()
Maximum number of JIDs that will be cached due to sending spam
URLs. If that limit is exceeded, the least recently used
entries are removed from the cache. Setting this option to 0
disables the caching feature. Note that separate caches are
used for each virtual host, and that the caches aren't
distributed across cluster nodes. The default value is 10000.
rtbl_services: [Service]
Query a RTBL service to get domains to block, as provided by
xmppbl.org. Please note right now this option only supports one
service in that list. For blocking spam and abuse on MUC
channels, please use mod_muc_rtbl for now. If only the host is
provided, the default node names will be assumed. If the node
name is different than spam_source_domains, you can setup the
custom node name with the option spam_source_domains_node. The
default value is an empty list of services.
Example:
rtbl_services:
- pubsub.server1.localhost:
spam_source_domains_node: actual_custom_pubsub_node
spam_domains_file: none | Path
Path to a plain text file containing a list of known spam
domains, one domain per line. Messages and subscription
requests sent from one of the listed domains are classified as
spam if sender is not in recipient's roster. This list of
domains gets merged with the one retrieved by an RTBL host if
any given. Use an absolute path, or the @CONFIG_PATH@
predefined keyword if the file is available in the
configuration directory. The default value is none.
spam_dump_file: false | true | Path
Path to the file to store blocked messages. Use an absolute
path, or the @LOG_PATH@ predefined keyword to store logs in the
same place that the other ejabberd log files. If set to false,
it doesn't dump stanzas, which is the default. If set to true,
it stores in "@LOG_PATH@/spam_dump_@HOST@.log".
spam_jids_file: none | Path
Path to a plain text file containing a list of known spammer
JIDs, one JID per line. Messages and subscription requests sent
from one of the listed JIDs are classified as spam. Messages
containing at least one of the listed JIDsare classified as
spam as well. Furthermore, the sender's JID will be cached, so
that future traffic originating from that JID will also be
classified as spam. Use an absolute path, or the @CONFIG_PATH@
predefined keyword if the file is available in the
configuration directory. The default value is none.
spam_urls_file: none | Path
Path to a plain text file containing a list of URLs known to be
mentioned in spam message bodies. Messages containing at least
one of the listed URLs are classified as spam. Furthermore, the
sender's JID will be cached, so that future traffic originating
from that JID will be classified as spam as well. Use an
absolute path, or the @CONFIG_PATH@ predefined keyword if the
file is available in the configuration directory. The default
value is none.
whitelist_domains_file: none | Path
Path to a file containing a list of domains to whitelist from
being blocked, one per line. If either it is in
spam_domains_file or more realistically in a domain sent by a
RTBL host (see option rtbl_services) then this domain will be
ignored and stanzas from there won't be blocked. Use an
absolute path, or the @CONFIG_PATH@ predefined keyword if the
file is available in the configuration directory. The default
value is none.
Example:
modules:
mod_antispam:
rtbl_services:
- xmppbl.org
spam_jids_file: "@CONFIG_PATH@/spam_jids.txt"
spam_dump_file: "@LOG_PATH@/spam/host-@HOST@.log"
mod_auth_fast
Note about this option: improved in 26.07.
The module adds support for XEP-0484: Fast Authentication Streamlining
Tokens that allows users to authenticate using self-managed tokens.
Available options:
db_type : mnesia | sql
Note about this option: improved in 26.07. Same as top-level
default_db option, but applied to this module only.
token_lifetime: timeout()
Time that tokens will be kept, measured from it's creation
time. Default value set to 30 days
token_refresh_age: timeout()
This time determines age of token, that qualifies for automatic
refresh. Default value set to 1 day
Example:
modules:
mod_auth_fast:
token_lifetime: 14days
mod_avatar
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.
Also, the module supports conversion between avatar image formats on
the fly.
The module depends on mod_vcard, mod_vcard_xupdate and mod_pubsub.
Available options:
convert: {From: To}
Defines image conversion rules: the format in From will be
converted to format in To. The value of From can also be
default, 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.
Example:
convert:
webp: jpg
default: png
rate_limit: Number
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 10.
mod_block_strangers
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'll just not receive message from
that entity. Enable this module if you want to drop SPAM messages.
Available options:
access: AccessName
The option is supposed to be used when allow_local_users and
allow_transports are not enough. It's an Access Rule where deny
means the stanza will be rejected; there's an exception if
option captcha is configured. And allow means the sender is
whitelisted and the stanza will pass through. The default value
is none, which means nothing is whitelisted.
allow_local_users: true | false
This option specifies if strangers from the same local host
should be accepted or not. The default value is true.
allow_transports: true | false
If set to true and some server's JID is in user's roster, then
messages from any user of this server are accepted even if no
subscription present. The default value is true.
captcha: true | false
Whether to generate CAPTCHA challenges in response to incoming
presence subscription requests from strangers. See also section
basic.md#captcha|CAPTCHA of the Configuration Guide. The
default value is false.
drop: true | false
This option specifies if strangers messages should be dropped
or not. The default value is true.
log: true | false
This option specifies if strangers' messages should be logged
(as info message) in ejabberd.log. The default value is false.
mod_blocking
The module implements XEP-0191: Blocking Command.
This module depends on mod_privacy where all the configuration is
performed.
The module has no options.
mod_bosh
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.
Available options:
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
json: true | false
This option has no effect.
max_concat: pos_integer() | infinity
This option limits the number of stanzas that the server will
send in a single bosh request. The default value is unlimited.
max_inactivity: timeout()
The option defines the maximum inactivity period. The default
value is 30 seconds.
max_pause: pos_integer()
Indicate the maximum length of a temporary session pause (in
seconds) that a client can request. The default value is 120.
prebind: true | false
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 false.
queue_type: ram | file
Same as top-level queue_type option, but applied to this module
only.
ram_db_type: mnesia | sql | redis
Same as top-level default_ram_db option, but applied to this
module only.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
Example:
listen:
-
port: 5222
module: ejabberd_c2s
-
port: 5443
module: ejabberd_http
request_handlers:
/bosh: mod_bosh
modules:
mod_bosh: {}
mod_caps
This module implements XEP-0115: Entity Capabilities. The main purpose
of the module is to provide PEP functionality (see mod_pubsub).
Available options:
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
mod_carboncopy
The module implements XEP-0280: Message Carbons. The module broadcasts
messages on all connected user resources (devices).
The module has no options.
mod_client_state
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.
A stanza is dropped from the queue if it's 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't be
queued, or if the queue size reaches a certain limit (currently 100
stanzas), or if the client becomes active again.
Available options:
queue_chat_states: true | false
Queue "standalone" chat state notifications (as defined in
XEP-0085: Chat State Notifications) while a client indicates
inactivity. The default value is true.
queue_pep: true | false
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 true.
queue_presence: true | false
While a client is inactive, queue presence stanzas that
indicate (un)availability. The default value is true.
mod_configure
Note about this option: improved in 25.10.
The module provides server configuration functionalities using
XEP-0030: Service Discovery and XEP-0050: Ad-Hoc Commands:
o List and discover outgoing s2s, online client sessions and all
registered accounts
o Most of the ad-hoc commands defined in XEP-0133: Service
Administration
o Additional custom ad-hoc commands specific to ejabberd
Ad-hoc commands from XEP-0133 that behave differently to the XEP:
o get-user-roster: returns standard fields instead of roster items
that client cannot display
Those ad-hoc commands from XEP-0133 do not include in the response the
client that executed the command:
o get-active-users-num
o get-idle-users-num
o get-active-users
o get-idle-users
Those ad-hoc commands from XEP-0133 are not implemented:
o edit-blacklist
o edit-whitelist
o edit-admin
This module requires mod_adhoc (to execute the commands), and
recommends mod_disco (to discover the commands).
Please notice that all the ad-hoc commands implemented by this module
have an equivalent API Command that you can execute using mod_adhoc_api
or any other API frontend.
Available options:
access: AccessName
Note about this option: added in 25.03. This option defines
which access rule will be used to control who is allowed to
access the features provided by this module. The default value
is configure.
Example:
acl:
admin:
user: sun@localhost
access_rules:
configure:
allow: admin
modules:
mod_configure:
access: configure
mod_conversejs
Note about this option: improved in 25.07.
This module serves a simple page for the Converse XMPP web browser
client.
To use this module, in addition to adding it to the modules section,
you must also enable it in listen -> ejabberd_http ->
listen-options.md#request_handlers|request_handlers.
Make sure either mod_bosh or
listen.md#ejabberd_http_ws|ejabberd_http_ws are enabled in at least one
request_handlers.
When conversejs_css and conversejs_script are auto, by default they
point to the public Converse client.
When this module is enabled in modules, it adds automatically a request
handler and link in WebAdmin. .
This module is available since ejabberd 21.12.
Available options:
bosh_service_url: auto | BoshURL
BOSH service URL to which Converse can connect to. The keyword
@HOST@ is replaced with the real virtual host name. If set to
auto, it will build the URL of the first configured BOSH
request handler. The default value is auto.
conversejs_css: auto | URL
Converse CSS URL. The keyword @HOST@ is replaced with the
hostname. The default value is auto.
conversejs_options: {Name: Value}
Note about this option: added in 22.05. Specify additional
options to be passed to Converse. See Converse configuration.
Only boolean, integer and string values are supported; lists
are not supported.
conversejs_plugins: [Filename]
List of additional local files to include as scripts in the
homepage. Please make sure those files are available in the
path specified in conversejs_resources option, in subdirectory
plugins/. Notice that libsignal is only required for OMEMO
encryption in Converse 13 or lower; Converse 14 uses and
includes libomemo. If using the public Converse client, then
"libsignal" gets replaced with the URL of the public library.
The default value is [].
conversejs_resources: Path
Note about this option: added in 22.05. Local path to the
Converse files. If not set, the public Converse client will be
used instead.
conversejs_script: auto | URL
Converse main script URL. The keyword @HOST@ is replaced with
the hostname. The default value is auto.
default_domain: Domain
Specify a domain to act as the default for user JIDs. The
keyword @HOST@ is replaced with the hostname. The default value
is @HOST@.
websocket_url: auto | WebSocketURL
A WebSocket URL to which Converse can connect to. The @HOST@
keyword is replaced with the real virtual host name. If set to
auto, it will build the URL of the first configured WebSocket
request handler. The default value is auto.
Examples:
Manually setup WebSocket url, and use the public Converse client:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/bosh: mod_bosh
/websocket: ejabberd_http_ws
/conversejs: mod_conversejs
modules:
mod_bosh: {}
mod_conversejs:
websocket_url: "ws://@HOST@:5280/websocket"
Host Converse locally and let auto detection of WebSocket and
Converse URLs:
listen:
-
port: 443
module: ejabberd_http
tls: true
request_handlers:
/websocket: ejabberd_http_ws
/conversejs: mod_conversejs
modules:
mod_conversejs:
conversejs_resources: "/home/ejabberd/conversejs-x.y.z/package/dist"
conversejs_plugins: ["libsignal-protocol.min.js"]
# File path is: /home/ejabberd/conversejs-x.y.z/package/dist/plugins/libsignal-protocol.min.js
Configure some additional options for Converse
modules:
mod_conversejs:
websocket_url: auto
conversejs_options:
auto_away: 30
clear_cache_on_logout: true
i18n: "pt"
locked_domain: "@HOST@"
message_archiving: always
theme: dracula
mod_delegation
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.
Warning
Security issue: Namespace delegation gives components access to
sensitive data, so permission should be granted carefully, only if
you trust the component.
Note
This module is complementary to mod_privilege but can also be used
separately.
Available options:
namespaces: {Namespace: Options}
If you want to delegate namespaces to a component, specify them
in this option, and associate them to an access rule. The
Options are:
access: AccessName
The option defines which components are allowed for
namespace delegation. The default value is none.
filtering: Attributes
The list of attributes. Currently not used.
Examples:
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 sat-pubsub.example.org component perform correctly disable
the mod_pubsub module.
access_rules:
external_pubsub:
allow: external_component
external_mam:
allow: external_component
acl:
external_component:
server: sat-pubsub.example.org
modules:
mod_delegation:
namespaces:
urn:xmpp:mam:1:
access: external_mam
http://jabber.org/protocol/pubsub:
access: external_pubsub
mod_disco
This module adds support for XEP-0030: Service Discovery. With this
module enabled, services on your server can be discovered by XMPP
clients.
Available options:
extra_domains: [Domain, ...]
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.
name: Name
A name of the server in the Service Discovery. This will only
be displayed by special XMPP clients. The default value is
ejabberd.
server_info: [Info, ...]
Specify additional information about the server, as described
in XEP-0157: Contact Addresses for XMPP Services. Every Info
element in the list is constructed from the following options:
modules: all | [Module, ...]
The value can be the keyword all, 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.
name: Name
The field var name that will be defined. See XEP-0157 for
some standardized names.
urls: [URI, ...]
A list of contact URIs, such as HTTP URLs, XMPP URIs and so
on.
Example:
server_info:
-
modules: all
name: abuse-addresses
urls: ["mailto:abuse@shakespeare.lit"]
-
modules: [mod_muc]
name: "Web chatroom logs"
urls: ["http://www.example.org/muc-logs"]
-
modules: [mod_disco]
name: feedback-addresses
urls:
- http://shakespeare.lit/feedback.php
- mailto:feedback@shakespeare.lit
- xmpp:feedback@shakespeare.lit
-
modules:
- mod_disco
- mod_vcard
name: admin-addresses
urls:
- mailto:xmpp@shakespeare.lit
- xmpp:admins@shakespeare.lit
mod_fail2ban
The module bans IPs that show the malicious signs. Currently only C2S
authentication failures are detected.
Unlike the standalone program, mod_fail2ban 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.
Warning
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.
Available options:
access: AccessName
Specify an access rule for whitelisting IP addresses or
networks. If the rule returns allow for a given IP address,
that address will never be banned. The AccessName should be of
type ip. The default value is none.
c2s_auth_ban_lifetime: timeout()
The lifetime of the IP ban caused by too many C2S
authentication failures. The default value is 1 hour.
c2s_max_auth_failures: Number
The number of C2S authentication failures to trigger the IP
ban. The default value is 20.
API Tags:
../../developer/ejabberd-api/admin-tags.md#accounts|accounts
mod_host_meta
Note about this option: added in 22.05.
This module serves small host-meta files as described in XEP-0156:
Discovering Alternative XMPP Connection Methods.
To use this module, in addition to adding it to the modules section,
you must also enable it in listen -> ejabberd_http ->
listen-options.md#request_handlers|request_handlers.
Notice it only works if listen.md#ejabberd_http|ejabberd_http has
listen-options.md#tls|tls enabled.
Available options:
bosh_service_url: undefined | auto | BoshURL
BOSH service URL to announce. The keyword @HOST@ is replaced
with the real virtual host name. If set to auto, it will build
the URL of the first configured BOSH request handler. The
default value is auto.
websocket_url: undefined | auto | WebSocketURL
WebSocket URL to announce. The keyword @HOST@ is replaced with
the real virtual host name. If set to auto, it will build the
URL of the first configured WebSocket request handler. The
default value is auto.
Example:
listen:
-
port: 443
module: ejabberd_http
tls: true
request_handlers:
/bosh: mod_bosh
/websocket: ejabberd_http_ws
/.well-known/host-meta: mod_host_meta
/.well-known/host-meta.json: mod_host_meta
modules:
mod_bosh: {}
mod_host_meta:
bosh_service_url: "https://@HOST@:5443/bosh"
websocket_url: "wss://@HOST@:5443/websocket"
mod_http_api
This module provides a ReST interface to call
../../developer/ejabberd-api/index.md|ejabberd API commands using JSON
data.
To use this module, in addition to adding it to the modules section,
you must also enable it in listen -> ejabberd_http ->
listen-options.md#request_handlers|request_handlers.
To use a specific API version N, when defining the URL path in the
request_handlers, add a vN. For example: /api/v2: mod_http_api.
To run a command, send a POST request to the corresponding URL:
http://localhost:5280/api/COMMAND-NAME
Available options:
default_version: integer() | string()
Note about this option: added in 24.12. 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 "24.06" in this
option implies 2. The default value is the latest version.
Example:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/api: mod_http_api
modules:
mod_http_api:
default_version: 2
mod_http_fileserver
Note about this option: improved docroot in 26.01.
This simple module serves files from the local disk over HTTP.
Available options:
accesslog: Path
File to log accesses using an Apache-like format. No log will
be recorded if this option is not specified.
content_types: {Extension: Type}
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:
Example:
content_types:
.avi: video/avi
.bmp: image/bmp
.bz2: application/x-bzip2
.css: text/css
.gif: image/gif
.gz: application/x-gzip
.html: text/html
.ico: image/vnd.microsoft.icon
.jar: application/java-archive
.jpeg: image/jpeg
.jpg: image/jpeg
.js: text/javascript
.json: application/json
.m4a: audio/mp4
.map: application/json
.mp3: audio/mpeg
.mp4: video/mp4
.mpeg: video/mpeg
.mpg: video/mpeg
.ogg: application/ogg
.pdf: application/pdf
.png: image/png
.rtf: application/rtf
.svg: image/svg+xml
.tiff: image/tiff
.ttf: font/ttf
.txt: text/plain
.wav: audio/wav
.wasm: application/wasm
.webp: image/webp
.woff: font/woff
.woff2: font/woff2
.xml: application/xml
.xpi: application/x-xpinstall
.xul: application/vnd.mozilla.xul+xml
.xz: application/x-xz
.zip: application/zip
custom_headers: {Name: Value}
Indicate custom HTTP headers to be included in all responses.
There are no custom headers by default.
default_content_type: Type
Specify the content type to use for unknown extensions. The
default value is application/octet-stream.
directory_indices: [Index, ...]
Indicate one or more directory index files, similarly to
Apache's DirectoryIndex 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.
docroot: PathDir | {PathURL, PathDir}
Note about this option: improved in 26.01. Directory to serve
the files from, or a map with several URL path (as specified in
listen-options.md#request_handlers|request_handlers) and their
corresponding directory. This is a mandatory option.
Example:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/pub/content: mod_http_fileserver
/share: mod_http_fileserver
/: mod_http_fileserver
modules:
mod_http_fileserver:
docroot:
/pub/content: /var/service/www
/share: /usr/share/javascript
/: /var/www
must_authenticate_with: [{Username, Hostname}, ...]
List of accounts that are allowed to use this service. Default
value: [].
Examples:
This example configuration will serve the files from the local
directory /var/www in the address
http://example.org:5280/pub/content/. In this example a new content
type ogg is defined, png is redefined, and jpg definition is
deleted:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/pub/content: mod_http_fileserver
modules:
mod_http_fileserver:
docroot: /var/www
accesslog: /var/log/ejabberd/access.log
directory_indices:
- index.html
- main.htm
custom_headers:
X-Powered-By: Erlang/OTP
X-Fry: "It's a widely-believed fact!"
content_types:
.ogg: audio/ogg
.png: image/png
default_content_type: text/html
mod_http_upload
Note about this option: added content_types in 26.01.
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 listen ->
ejabberd_http -> listen-options.md#request_handlers|request_handlers.
Available options:
access: AccessName
This option defines the access rule to limit who is permitted
to use the HTTP upload service. The default value is local. If
no access rule of that name exists, no user will be allowed to
use the service.
append_module_config : {UploadHost: Options}
Note about this option: added in 26.07. Add a few specific
options to a certain upload host previously defined in the
mod_http_upload hosts option. Right now only name and vcard can
be defined here. This is similar to the toplevel
append_host_config option, but in this case it's applied to
this module options.
Example:
modules:
mod_http_upload:
hosts:
- service1.@HOST@
- service2.@HOST@
name: "Service General"
append_module_config:
service1.localhost:
name: "Service 1"
service2.example.net:
name: "Service 2"
content_types: {Extension: Type}
Note about this option: added in 26.01. Specify mappings of
extension to content type, similarly to the option
content_types of mod_http_fileserver.
custom_headers: {Name: Value}
This option specifies additional header fields to be included
in all HTTP responses. By default no custom headers are
included.
dir_mode: Permission
This option defines the permission bits of the docroot
directory and any directories created during file uploads. The
bits are specified as an octal number (see the chmod(1) manual
page) within double quotes. For example: "0755". The default is
undefined, which means no explicit permissions will be set.
docroot: Path
Uploaded files are stored below the directory specified (as an
absolute path) with this option. The keyword @HOME@ is replaced
with the home directory of the user running ejabberd, and the
keyword @HOST@ with the virtual host name. The default value is
"@HOME@/upload".
external_secret: Text
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 Prosody's mod_http_upload_external:
Implementation. There is no default value.
file_mode: Permission
This option defines the permission bits of uploaded files. The
bits are specified as an octal number (see the chmod(1) manual
page) within double quotes. For example: "0644". The default is
undefined, which means no explicit permissions will be set.
get_url: URL
This option specifies the initial part of the GET URLs used for
downloading the files. The default value is undefined. When
this option is undefined, this option is set to the same value
as put_url. The keyword @HOST@ is replaced with the virtual
host name. NOTE: if GET requests are handled by this module,
the get_url must match the put_url. Setting it to a different
value only makes sense if an external web server or
mod_http_fileserver is used to serve the uploaded files.
host
Deprecated. Use hosts instead.
hosts: [Host, ...]
This option defines the Jabber IDs of the service. If the hosts
option is not specified, the only Jabber ID will be the
hostname of the virtual host with the prefix "upload.". The
keyword @HOST@ is replaced with the real virtual host name.
jid_in_url: node | sha1
When this option is set to node, the node identifier of the
user's JID (i.e., the user name) is included in the GET and PUT
URLs generated by mod_http_upload. Otherwise, a SHA-1 hash of
the user's bare JID is included instead. The default value is
sha1.
max_size: Size
This option limits the acceptable file size. Either a number of
bytes (larger than zero) or infinity must be specified. The
default value is 104857600.
name: Name
A name of the service in the Service Discovery. The default
value is "HTTP File Upload". Please note this will only be
displayed by some XMPP clients.
put_url: URL
This option specifies the initial part of the PUT URLs used for
file uploads. The keyword @HOST@ is replaced with the virtual
host name. And @HOST_URL_ENCODE@ is replaced with the host name
encoded for URL, useful when your virtual hosts contain
non-latin characters. NOTE: different virtual hosts cannot use
the same PUT URL. The default value is
"https://@HOST@:5443/upload".
rm_on_unregister: true | false
This option specifies whether files uploaded by a user should
be removed when that user is unregistered. The default value is
true.
secret_length: Length
This option defines the length of the random string included in
the GET and PUT URLs generated by mod_http_upload. The minimum
length is 8 characters, but it is recommended to choose a
larger value. The default value is 40.
service_url
Deprecated.
thumbnail: true | false
This option specifies whether ejabberd should create thumbnails
of uploaded images. If a thumbnail is created, a
element that contains the download and some metadata is
returned with the PUT response. The default value is false.
vcard: vCard
A custom vCard of the service that will be displayed by some
XMPP clients in Service Discovery. The value of vCard is a YAML
map constructed from an XML representation of vCard. Since the
representation has no attributes, the mapping is
straightforward.
Example:
# This XML representation of vCard:
#
# Conferences
#
#
# Elm Street
#
#
#
# is translated to:
vcard:
fn: Conferences
adr:
-
work: true
street: Elm Street
Example:
listen:
-
port: 5443
module: ejabberd_http
tls: true
request_handlers:
/upload: mod_http_upload
modules:
mod_http_upload:
docroot: /ejabberd/upload
put_url: "https://@HOST@:5443/upload"
mod_http_upload_quota
This module adds quota support for mod_http_upload.
This module depends on mod_http_upload.
Available options:
access_hard_quota: AccessName
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
access_soft_quota). The default value is hard_upload_quota.
access_soft_quota: AccessName
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
access_hard_quota option for details. The default value is
soft_upload_quota.
max_days: Days
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 docroot directory, once per day. The
default value is infinity.
Examples:
Notice it's not necessary to specify the access_hard_quota and
access_soft_quota 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:
shaper_rules:
soft_upload_quota:
1000: all # MiB
hard_upload_quota:
1100: all # MiB
modules:
mod_http_upload: {}
mod_http_upload_quota:
max_days: 100
mod_invites
Note about this option: improved in 26.07.
Allow User Invitation and Account Creation to create out-of-band links
to onboard others onto the XMPP network and establish a mutual
subscription. This implements XEP-0379: Pre-Authenticated Roster
Subscription, XEP-0401: Ad-hoc Account Invitation Generation, and
XEP-0445: Pre-Authenticated In-Band Registration.
These invitations are created as XMPP URIs either via ad-hoc commands
or via API commands (like generate_invite API and
generate_invite_with_username API), are then meant to be sent
out-of-band.
The receiving user should have installed a client that supports those
invitations. Since this has proven to be a common obstacle for easy
adoption, this module comes with an optional landing page parameter,
that can either be some external service like an installation of
easy-xmpp-invitation, a third-party service like JoinJabber or for
convenience a built-in service. This landing page will then guide the
recipient with setting up a client and creating an account if required.
In order to use the included landing page feature, you have to set
landing_page to either auto or an URL template like https://{{ host
}}/invites/{{ invite.token }} if your server setup includes a so called
reverse proxy. Furthermore you need to connect this module as a handler
of an ejabberd_http listener as shown at the example below.
For convenience there's now also a start page included at wherever you
mount mod_invites at the ejabberd_http handler. This start page will
allow people to generate invites by giving their username and password.
As such the URL should be protected by HTTPS. The main use-case is when
people have only clients, that don't support generating invites
natively.
If you'd rather want to use an external service, set landing_page to
something like http://{{ host }}:8080/easy-xmpp-invites/#{{
invite.uri|strip_protocol }} or https://invites.joinjabber.org/#{{
invite.uri|strip_protocol }}.
Available options:
access_create_account: Access Rule Name
This is the name of an access rule that specifies who is
allowed to create invites of create account. The default value
is none, i.e. nobody is able to create such invites.
Furthermore it applies to roster invites and allows to do
in-band registration (IBR) if the sending user is allowed by
this rule. Users from the admin ACL are always allowed to
create those invites.
Example:
mod_invites:
access_create_account: local
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
landing_page: none | auto | LandingPageURLTemplate
Whether or not to use a landing page for the invites that are
being created. If using a template URL this can be either be
external or internal. Template variables include host,
invite.token and invite.uri, there are also filters defined,
most notably strip_protocol. Here's an example: http://{{ host
}}:8080/easy-xmpp-invites/#{{ invite.uri|strip_protocol }}. For
convenience you can choose auto here and the ejabberd_http
handler for mod_invites will be used to construct the landing
page URL. Default is none.
max_invites: pos_integer() | infinity
Maximum number of create account invites that can be created by
an individual user. Users that match the admin ACL are exempt
from this limitation. Furthermore it restricts the use of
roster invites for account creation. Default is infinity.
site_name: Site Name
A human readable name for your site. E.g. "My Beautiful
Laundrette". Used in landing page templates.
templates_dir: Path
The directory containing templates and static files used for
landing page and web registration form. Only needs to be set if
you want to ship your own set of templates or list of
recommended apps.
token_expire_seconds: pos_integer()
Number of seconds until token expires. Default value is 432000
(that is five days: 5 * 24 * 60 * 60)
webchat_url: none | auto | Webchat URL
Note about this option: added in 26.03. URL to a webchat
client. Upon manual registration through web-form this will be
recommended in order to get started. If auto is chosen, we pick
the mod_conversejs from the listeners section. Default is auto.
Examples:
Basic configuration with landing page but without creating
accounts, just roster invites:
listen:
-
port: 5281
module: ejabberd_http
request_handlers:
/invites: mod_invites
# [...]
modules:
mod_invites:
landing_page: auto
To allow only admin users to create invites of create account and
disable regular in-band registration, you would have a config like
this:
acl:
admin:
- user: "my_admin_user@example.com"
access_rules:
register:
allow: admin
modules:
mod_invites:
landing_page: auto
mod_register:
allow_modules:
- mod_invites
If you want all your users to be able to send create account
invites, you would configure your server like this instead. Note
that the names of the access rules are just examples and you're
free to change them.
acl:
local:
user_regexp: ""
access_rules:
create_account_invite:
allow: local
modules:
mod_invites:
access_create_account: create_account_invite
landing_page: auto
mod_register:
allow_modules:
- mod_invites
mod_jidprep
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.
Available options:
access: AccessName
This option defines which access rule will be used to control
who is allowed to use this service. The default value is local.
mod_last
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.
Available options:
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
mod_legacy_auth
The module implements XEP-0078: Non-SASL Authentication.
Note
This type of authentication was obsoleted in 2008 and you unlikely
need this module unless you have something like outdated Jabber
bots.
The module has no options.
mod_mam
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.
Note
Mnesia backend for mod_mam is not recommended: it's limited to 2GB
and often gets corrupted when reaching this limit. SQL backend is
recommended. Namely, for small servers SQLite is a preferred choice
because it's very easy to configure.
Available options:
access_preferences: AccessName
This access rule defines who is allowed to modify the MAM
preferences. The default value is all.
archive_muc_as_mucsub: true | false
Note about this option: added in 25.10. When this option is
enabled incoming groupchat messages for users that have mucsub
subscription to a room from which message originated will have
those messages archived after being converted to mucsub event
messages.The default value is false.
assume_mam_usage: true | false
This option determines how ejabberd's stream management code
(see mod_stream_mgmt) 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's MAM archive if this option is set to true.
In this case, ejabberd assumes those messages will be retrieved
from the archive. The default value is false.
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
clear_archive_on_room_destroy: true | false
Whether to destroy message archive of a room (see mod_muc) when
it gets destroyed. The default value is true.
compress_xml: true | false
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 false.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
default: always | never | roster
The option defines default policy for chat history. When always
is set every chat message is stored. With roster only chat
history with contacts from user's roster is stored. And never
fully disables chat history. Note that a client can change its
policy via protocol commands. The default value is never.
request_activates_archiving: true | false
If the value is true, no messages are stored for a user until
their client issue a MAM request, regardless of the value of
the default option. Once the server received a request, that
user's messages are archived as usual. The default value is
false.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
user_mucsub_from_muc_archive: true | false
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 false.
API Tags: ../../developer/ejabberd-api/admin-tags.md#mam|mam,
../../developer/ejabberd-api/admin-tags.md#purge|purge
mod_matrix_gw
Note about this option: improved in 25.08.
Matrix gateway. Supports room versions 9, 10 and 11 since ejabberd
25.03; room versions 4 and higher since ejabberd 25.07; room version 12
(hydra rooms) since ejabberd 25.08. Erlang/OTP 25 or higher is required
to use this module. This module is available since ejabberd 24.02.
Available options:
host: Host
This option defines the Jabber IDs of the service. If the host
option is not specified, the Jabber ID will be the hostname of
the virtual host with the prefix "matrix.". The keyword @HOST@
is replaced with the real virtual host name.
key: string()
Value of the matrix signing key, in base64.
key_name: string()
Name of the matrix signing key.
leave_timeout: integer()
Delay in seconds between a user leaving a MUC room and sending
leave Matrix event.
matrix_domain: Domain
Specify a domain in the Matrix federation. The keyword @HOST@
is replaced with the hostname. The default value is @HOST@.
matrix_id_as_jid: true | false
If set to true, 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 user@matrixdomain.tld to a
Matrix user identifier @user:matrixdomain.tld. When set to
false, 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
@user:matrixdomain.tld, the client must send a message to the
JID user%matrixdomain.tld@matrix.myxmppdomain.tld, where
matrix.myxmppdomain.tld is the JID of the gateway service as
set by the host option. The default is false.
notary_servers: [Server, ...]
A list of notary servers.
Example:
listen:
-
port: 8448
module: ejabberd_http
tls: true
request_handlers:
"/_matrix": mod_matrix_gw
modules:
mod_matrix_gw:
key_name: "key1"
key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
matrix_id_as_jid: true
mod_metrics
This module sends events to external backend (by now only grapherl is
supported). Supported events are:
o sm_register_connection
o sm_remove_connection
o user_send_packet
o user_receive_packet
o s2s_send_packet
o s2s_receive_packet
o register_user
o remove_user
o offline_message
When enabled, every call to these hooks triggers a counter event to be
sent to the external backend.
Available options:
ip: IPv4Address
IPv4 address where the backend is located. The default value is
127.0.0.1.
port: Port
An internet port number at which the backend is listening for
incoming connections/packets. The default value is 11111.
mod_mix
Note about this option: added in 16.03 and improved in 19.02.
This module is an experimental implementation of XEP-0369: Mediated
Information eXchange (MIX). It's asserted that the MIX protocol is
going to replace the MUC protocol in the future (see mod_muc).
To learn more about how to use that feature, you can refer to our
tutorial: ../../tutorials/mix-010.md|Getting started with MIX
The module depends on mod_mam.
Available options:
access_create: AccessName
An access rule to control MIX channels creations. The default
value is all.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
host
Deprecated. Use hosts instead.
hosts: [Host, ...]
This option defines the Jabber IDs of the service. If the hosts
option is not specified, the only Jabber ID will be the
hostname of the virtual host with the prefix "mix.". The
keyword @HOST@ is replaced with the real virtual host name.
name: Name
A name of the service in the Service Discovery. This will only
be displayed by special XMPP clients. The default value is
Channels.
mod_mix_pam
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).
Note
mod_mix is not required for this module to work, however, without
mod_mix_pam the MIX functionality of your local XMPP clients will
be impaired.
Available options:
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
mod_mqtt
This module adds ../guide/mqtt/index.md|support for the MQTT protocol
version 3.1.1 and 5.0. Remember to configure mod_mqtt in modules and
listen sections.
Available options:
access_publish: {TopicFilter: AccessName}
Access rules to restrict access to topics for publishers. By
default there are no restrictions.
access_subscribe: {TopicFilter: AccessName}
Access rules to restrict access to topics for subscribers. By
default there are no restrictions.
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_missed: true | false
Same as top-level cache_missed option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
match_retained_limit: pos_integer() | infinity
The option limits the number of retained messages returned to a
client when it subscribes to some topic filter. The default
value is 1000.
max_queue: Size
Maximum queue size for outgoing packets. The default value is
5000.
max_topic_aliases: 0..65535
The maximum number of aliases a client is able to associate
with the topics. The default value is 100.
max_topic_depth: Depth
The maximum topic depth, i.e. the number of slashes (/) in the
topic. The default value is 8.
queue_type: ram | file
Same as top-level queue_type option, but applied to this module
only.
ram_db_type: mnesia
Same as top-level default_ram_db option, but applied to this
module only.
session_expiry: timeout()
The option specifies how long to wait for an MQTT session
resumption. When 0 is set, the session gets destroyed when the
underlying client connection is closed. The default value is 5
minutes.
use_cache: true | false
Same as top-level use_cache option, but applied to this module
only.
mod_mqtt_bridge
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.
Available options:
replication_user: JID
Identifier of a user that will be assigned as owner of local
changes.
servers: {ServerUrl: {Key: Value}}
Declaration of data to share for each ServerUrl. Server URLs
can use schemas: mqtt, mqtts (mqtt with tls), mqtt5, mqtt5s
(both to trigger v5 protocol), ws, wss, ws5, wss5. Keys must
be:
authentication: {AuthKey: AuthValue}
List of authentication information, where AuthKey can be:
username and password fields, or certfile pointing to
client certificate. Certificate authentication can be used
only with mqtts, mqtt5s, wss, wss5.
publish: {LocalTopic: RemoteTopic}
Either publish or subscribe must be set, or both.
subscribe: {RemoteTopic: LocalTopic}
Either publish or subscribe must be set, or both.
Example:
modules:
mod_mqtt_bridge:
replication_user: "mqtt@xmpp.server.com"
servers:
"mqtt://server.com":
authentication:
certfile: "/etc/ejabberd/mqtt_server.pem"
publish:
"localA": "remoteA" # local changes to 'localA' will be replicated on remote server as 'remoteA'
"topicB": "topicB"
subscribe:
"remoteB": "localB" # changes to 'remoteB' on remote server will be stored as 'localB' on local server
mod_muc
Note about this option: incorporated mod_muc_occupantid in 26.02.
This module provides support for Multi-User Chat (MUC). Users can
discover existing rooms, join or create them. Occupants of a room can
chat in public or have private chats.
Protocols implemented in this module:
o XEP-0045: Multi-User Chat
o XEP-0249: Direct MUC Invitations
o XEP-0421: Occupant identifiers for semi-anonymous MUCs
o XEP-0486: MUC Avatars
o Muc/Sub: Multi-User Chat Subscriptions
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.
Available options:
access: AccessName
You can specify who is allowed to use the Multi-User Chat
service. By default everyone is allowed to use it.
access_admin: AccessName
This option specifies who is allowed to administrate the
Multi-User Chat service. The default value is none, 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.
access_create: AccessName
To configure who is allowed to create new rooms at the
Multi-User Chat service, this option can be used. The default
value is all, which means everyone is allowed to create rooms.
access_mam: AccessName
To configure who is allowed to modify the mam room option. The
default value is all, which means everyone is allowed to modify
that option.
access_persistent: AccessName
To configure who is allowed to modify the persistent room
option. The default value is all, which means everyone is
allowed to modify that option.
access_register: AccessName
Note 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 all for
backward compatibility, which means that any user is allowed to
register any free nick in the MUC service and in the rooms.
append_module_config : {MUCHost: Options}
Note about this option: added in 26.07. Add a few specific
options to a certain MUC host previously defined in the mod_muc
hosts option. This is similar to the toplevel
append_host_config option, but in this case it's applied to the
mod_muc options.
Example:
modules:
mod_muc:
hosts:
- service1.@HOST@
- service2.@HOST@
name: "Service General"
append_module_config:
service1.localhost:
name: "Service 1"
service2.example.net:
name: "Service 2"
cleanup_affiliations_on_start: true | false
Note about this option: added in 22.05. Remove affiliations for
non-existing local users on startup. The default value is
false.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
default_room_options: Options
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 Options are:
allow_change_subj: true | false
Allow occupants to change the subject. The default value is
true.
allow_private_messages_from_visitors: anyone | moderators |
nobody
Visitors can send private messages to other occupants. The
default value is anyone which means visitors can send
private messages to any occupant.
allow_query_users: true | false
Occupants can send IQ queries to other occupants. The
default value is true.
allow_subscription: true | false
Allow users to subscribe to room events as described in
../../developer/xmpp-clients-bots/extensions/muc-sub.md|Multi-User
Chat Subscriptions. The default value is false.
allow_user_invites: true | false
Allow occupants to send invitations. The default value is
false.
allow_visitor_nickchange: true | false
Allow visitors to change nickname. The default value is
true.
allow_visitor_status: true | false
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 true.
allow_voice_requests: true | false
Allow visitors in a moderated room to request voice. The
default value is true.
allowpm: anyone | participants | moderators | none
Who can send private messages. The default value is anyone.
anonymous: true | false
The room is anonymous: occupants don't 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
true.
captcha_protected: true | false
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
basic.md#captcha|CAPTCHA in order to accept their join in
the room. The default value is false.
description: Room Description
Short description of the room. The default value is an
empty string.
enable_hats: true | false
Note about this option: improved in 25.10. Allow extended
roles as defined in XEP-0317: Hats. For ejabberd older than
25.10 see the ../../tutorials/muc-hats.md|MUC Hats page.
The default value is true.
lang: Language
Preferred language for the discussions in the room. The
language format should conform to RFC 5646. There is no
value by default.
logging: true | false
The public messages are logged using mod_muc_log. The
default value is false.
mam: true | false
Enable message archiving. Implies mod_mam is enabled. The
default value is false.
max_users: Number
Maximum number of occupants in the room. The default value
is 200.
members_by_default: true | false
The occupants that enter the room are participants by
default, so they have "voice". The default value is true.
members_only: true | false
Only members of the room can enter. The default value is
false.
moderated: true | false
Only occupants with "voice" can send public messages. The
default value is true.
password: Password
Password of the room. Implies option password_protected set
to true. There is no default value.
password_protected: true | false
The password is required to enter the room. The default
value is false.
persistent: true | false
The room persists even if the last participant leaves. The
default value is false.
presence_broadcast: [Role]
List of roles for which presence is broadcasted. The list
can contain one or several of: moderator, participant,
visitor. The default value is shown in the example below:
Example:
presence_broadcast:
- moderator
- participant
- visitor
public: true | false
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 true.
public_list: true | false
The list of participants is public, without requiring to
enter the room. The default value is true.
pubsub: PubSub Node
XMPP URI of associated Publish/Subscribe node. The default
value is an empty string.
title: Room Title
A human-readable title of the room. There is no default
value
vcard: vCard
A custom vCard for the room. See the equivalent mod_muc
option.The default value is an empty string.
vcard_xupdate: undefined | external | AvatarHash
Set the hash of the avatar image. The default value is
undefined.
voice_request_min_interval: Number
Minimum interval between voice requests, in seconds. The
default value is 1800.
hibernation_timeout: infinity | Seconds
Timeout before hibernating the room process, expressed in
seconds. The default value is infinity.
history_size: Size
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 0
disables the history feature and, as a result, nothing is kept
in memory. The default value is 20. 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're only using modern clients and have mod_mam
module loaded.
host
Deprecated. Use hosts instead.
hosts: [Host, ...]
This option defines the Jabber IDs of the service. If the hosts
option is not specified, the only Jabber ID will be the
hostname of the virtual host with the prefix "conference.". The
keyword @HOST@ is replaced with the real virtual host name.
max_captcha_whitelist: Number
Note 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 infinity.
max_password: Number
Note 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 infinity.
max_room_desc: Number
This option defines the maximum number of characters that Room
Description can have when configuring the room. The default
value is infinity.
max_room_id: Number
This option defines the maximum number of characters that Room
ID can have when creating a new room. The default value is
infinity.
max_room_name: Number
This option defines the maximum number of characters that Room
Name can have when configuring the room. The default value is
infinity.
max_rooms_discoitems: Number
When there are more rooms than this Number, only the non-empty
ones are returned in a Service Discovery query. The default
value is 100.
max_user_conferences: Number
This option defines the maximum number of rooms that any given
user can join. The default value is 100. 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.
max_users: Number
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 200.
max_users_admin_threshold: Number
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 5.
max_users_presence: Number
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 1000.
min_message_interval: Number
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 0.4 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.
min_presence_interval: Number
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 4 seconds.
name: string()
The value of the service name. This name is only visible in
some clients that support XEP-0030: Service Discovery. The
default is Chatrooms.
preload_rooms: true | false
Whether to load all persistent rooms in memory on startup. If
disabled, the room is only loaded on first participant join.
The default is true. It makes sense to disable room preloading
when the number of rooms is high: this will improve server
startup time and memory consumption.
queue_type: ram | file
Same as top-level queue_type option, but applied to this module
only.
ram_db_type: mnesia | sql
Same as top-level default_ram_db option, but applied to this
module only.
regexp_room_id: string()
This option defines the regular expression that a Room ID must
satisfy to allow the room creation. The default value is the
empty string.
room_shaper: none | ShaperName
This option defines shaper for the MUC rooms. The default value
is none.
user_message_shaper: none | ShaperName
This option defines shaper for the users messages. The default
value is none.
user_presence_shaper: none | ShaperName
This option defines shaper for the users presences. The default
value is none.
vcard: vCard
A custom vCard of the service that will be displayed by some
XMPP clients in Service Discovery. The value of vCard is a YAML
map constructed from an XML representation of vCard. Since the
representation has no attributes, the mapping is
straightforward.
Example:
# This XML representation of vCard:
#
# Conferences
#
#
# Elm Street
#
#
#
# is translated to:
vcard:
fn: Conferences
adr:
-
work: true
street: Elm Street
mod_muc_admin
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 depends on mod_muc.
Available options:
subscribe_room_many_max_users: Number
Note about this option: added in 22.05. How many users can be
subscribed to a room at once using the subscribe_room_many API.
The default value is 50.
API Tags: ../../developer/ejabberd-api/admin-tags.md#muc|muc,
../../developer/ejabberd-api/admin-tags.md#muc_room|muc_room,
../../developer/ejabberd-api/admin-tags.md#muc_sub|muc_sub
mod_muc_log
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.
Features:
o Room details are added on top of each page: room title, JID,
author, subject and configuration.
o The room JID in the generated HTML is a link to join the room
(using XMPP URI).
o Subject and room configuration changes are tracked and displayed.
o Joins, leaves, nick changes, kicks, bans and /me are tracked and
displayed, including the reason if available.
o Generated HTML files are XHTML 1.0 Transitional and CSS compliant.
o Timestamps are self-referencing links.
o Links on top for quicker navigation: Previous day, Next day, Up.
o CSS is used for style definition, and a custom CSS file can be
used.
o URLs on messages and subjects are converted to hyperlinks.
o Timezone used on timestamps is shown on the log files.
o A custom link can be added on top of each page.
The module depends on mod_muc.
Available options:
access_log: AccessName
This option restricts which occupants are allowed to enable or
disable room logging. The default value is muc_admin. NOTE: for
this default setting you need to have an access rule for
muc_admin in order to take effect.
cssfile: Path | URL
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 Path to local file or an URL to a
remote file. By default a predefined CSS will be embedded into
the HTML page.
dirname: room_jid | room_name
Configure the name of the room directory. If set to room_jid,
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 room_jid.
dirtype: subdirs | plain
The type of the created directories can be specified with this
option. If set to subdirs, 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 subdirs.
file_format: html | plaintext
Define the format of the log files: html stores in HTML format,
plaintext stores in plain text. The default value is html.
file_permissions: {mode: Mode, group: Group}
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:
Example:
file_permissions:
mode: 644
group: 33
outdir: Path
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
www/muc.
spam_prevention: true | false
If set to true, a special attribute is added to links that
prevent their indexation by search engines. The default value
is true, which mean that nofollow attributes will be added to
user submitted links.
timezone: local | universal
The time zone for the logs is configurable with this option. If
set to local, 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 local.
top_link: {URL: Text}
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:
Example:
top_link:
/: Home
url: URL
A top level URL where a client can access logs of a particular
conference. The conference name is appended to the URL if
dirname option is set to room_name or a conference JID is
appended to the URL otherwise. There is no default value.
mod_muc_rtbl
Note about this option: added in 23.04.
This module implement Real-time blocklists for MUC rooms.
It works by observing remote pubsub node conforming with specification
described in https://xmppbl.org/.
Available options:
rtbl_node: PubsubNodeName
Name of pubsub node that should be used to track blocked users.
The default value is muc_bans_sha256.
rtbl_server: Domain
Domain of xmpp server that serves block list. The default value
is xmppbl.org
mod_multicast
This module implements a service for XEP-0033: Extended Stanza
Addressing.
Available options:
access: Access
The access rule to restrict who can send packets to the
multicast service. Default value: all.
host
Deprecated. Use hosts instead.
hosts: [Host, ...]
This option defines the Jabber IDs of the service. If the hosts
option is not specified, the only Jabber ID will be the
hostname of the virtual host with the prefix "multicast.". The
keyword @HOST@ is replaced with the real virtual host name.
Please note: this module only uses the first vhost defined in
this option.
limits: Sender: Stanza: Number
Specify a list of custom limits which override the default ones
defined in XEP-0033. Limits are defined per sender type and
stanza type, where:
o sender can be: local or remote.
o stanza can be: message or presence.
o number can be a positive integer or infinite.
Example:
# Default values:
local:
message: 100
presence: 100
remote:
message: 20
presence: 20
name
Service name to provide in the Info query to the Service
Discovery. Default is "Multicast".
vcard
vCard element to return when queried. Default value is
undefined.
Example:
# 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
mod_offline
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.
The delete_expired_messages API allows to delete expired messages, and
delete_old_messages API deletes older ones.
Available options:
access_max_user_messages: AccessName
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
error is returned to the sender. The
default value is max_user_offline_messages.
bounce_groupchat: true | false
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
mod_offline. 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 false, meaning the
optimization is enabled.
cache_life_time: timeout()
Same as top-level cache_life_time option, but applied to this
module only.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied to this module
only.
db_type: mnesia | sql
Same as top-level default_db option, but applied to this module
only.
store_empty_body: true | false | unless_chat_state
Whether or not to store messages that lack a element.
The default value is unless_chat_state, which tells ejabberd to
store messages even if they lack the