This section describes top level options of ejabberd.
access_rules: {AccessName: {allow|deny:
ACLRules|ACLName}}
This option defines Access Rules. Each access rule is
assigned a name that can be referenced from other parts of the configuration
file (mostly from
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}}
The option defines 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
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. 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 anonymous protocol will be used:
•login_anon means that the anonymous login
method will be used.
•sasl_anon means that the SASL Anonymous
method will be used.
•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 →
API Permissions.
append_host_config: {Host: Options}
To define specific ejabberd modules in a virtual host,
you can define the global modules option with the common modules, and
later add specific modules to certain virtual hosts. To accomplish that,
append_host_config option can be used.
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_method: [mnesia | sql | anonymous | external | jwt
| ldap | pam, ...]
A list of 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 ejabberd-contrib Git
repository. Please refer to that module’s README file for
details.
Note about the next option: improved in 20.01:
auth_password_format: plain | scram
The option defines in what format the users passwords are
stored:
•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.
•scram: The password is not stored, only
some information that allows one 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. The default value is plain.
auth_scram_hash: sha | sha256 | sha512
Hash algorithm that should be used to store password in
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_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
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.
Note about the next option: improved in 23.01:
captcha_cmd: Path | ModuleName
Full path to a script that generates CAPTCHA images.
@VERSION@ is replaced with ejabberd version number in XX.YY format. @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.
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 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
An URL where CAPTCHA requests should be sent. NOTE: you
need to configure request_handlers for ejabberd_http listener as
well. There is no default value.
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.
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
Default persistent storage for ejabberd. Modules and
other components (e.g. authentication) may have its own value. The default
value is mnesia.
default_ram_db: mnesia | redis | sql
Default volatile (in-memory) storage for ejabberd.
Modules and other components (e.g. session management) may have its own value.
The default value is mnesia.
define_macro: {MacroName: MacroValue}
Defines a macro. The value can be any valid arbitrary
YAML value. For convenience, it’s recommended to define a
MacroName in capital letters. Duplicated macros are not allowed. Macros
are processed after additional configuration files have been included, so it
is possible to use macros that are defined in configuration files included
before the usage. It is possible to use a
MacroValue in the definition
of another macro.
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.
domain_balancing: {Domain: Options}
An algorithm to 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: random | source | destination | bare_source |
bare_destination
How to deliver stanzas to connected components:
random - an instance is chosen at random; destination - an
instance is chosen by the full JID of the packet’s to attribute;
source - by the full JID of the packet’s from attribute;
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. The
default value is random.
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, 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
external 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 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 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, ...]
The option defines a list containing one or more domains
that ejabberd will serve. This is a mandatory option.
include_config_file: [Filename, ...] | {Filename:
Options}
Read additional configuration 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.
jwt_auth_only_rule: AccessName
This ACL rule defines accounts that can use only this
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. This option allows one to specify other JWT
field name where the JID is defined.
jwt_key: FilePath
Path to the file that contains the JWK Key. The default
value is undefined.
language: Language
The option defines the 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. When no servers listed in ldap_servers option are reachable,
ejabberd will try to connect to these backup servers. The default is an empty
list, i.e. no backup servers specified. WARNING: ejabberd doesn’t try
to reconnect back to the main servers when they become operational again, so
the only way to restore these connections is to restart ejabberd. This
limitation might be fixed in future releases.
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.
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
Modules section for details.
Note about the next option: added in 22.10:
log_burst_limit_count: Number
The number of messages to accept in
log_burst_limit_window_time period before starting to drop them. Default
500
Note about the next option: added in 22.10:
log_burst_limit_window_time: Number
The time period to rate-limit log messages by. Defaults
to 1 second.
Note about the next option: added in 23.01:
log_modules_fully: [Module, ...]
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
10485760 (that is, 10 Mb).
loglevel: none | emergency | alert | critical | error |
warning | notice | info | debug
Verbosity of log files generated by ejabberd. 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}
The option for modules configuration. See Modules section
for details.
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 30 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
Whether to use new SQL schema. All schemas are
located at https://github.com/processone/ejabberd/tree/23.01/sql. There are
two schemas available. The default legacy schema allows one to store one XMPP
domain into one ejabberd database. The new schema allows one to handle
several XMPP domains in a single ejabberd database. Using this new
schema is best when serving several XMPP domains and/or changing domains from
time to time. This avoid need to manage several databases and handle complex
configuration changes. The default depends on configuration flag
--enable-new-sql-schema which is set at compile time.
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.
Note about the next option: added in 21.01:
oauth_cache_rest_failure_life_time: timeout()
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 allow.
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.
Note about the next option: changed in 23.01:
outgoing_s2s_families: [ipv6 | ipv4, ...]
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.
Note about the next option: added in 20.12:
outgoing_s2s_ipv4_address: Address
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.
Note about the next option: added in 20.12:
outgoing_s2s_ipv6_address: Address
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 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 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 Redis server. The default is 1 second.
redis_db: Number
Redis database number. The default is 0.
redis_password: Password
The password to the Redis server. The default is an empty
string, i.e. no password.
redis_pool_size: Number
The number of simultaneous connections to the Redis
server. The default value is 10.
redis_port: 1..65535
The port where the Redis server is accepting connections.
The default is 6379.
redis_queue_type: ram | file
The type of request queue for the 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: Hostname
A hostname or an IP address of the Redis server. The
default 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.
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.
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 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 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:
ACLRule|ACLName}}
An entry allowing to declaring shaper 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: Database
An SQL database name. For SQLite this must be a full path
to a database file. The default value is ejabberd.
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.
Note about the next option: added in 20.12:
sql_odbc_driver: Path
Path to the ODBC driver to use to connect to a Microsoft
SQL Server database. This option is only valid if the sql_type option
is set to mssql. 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.
Note about the next option: added in 20.01:
sql_prepared_statements: true | false
This option is true by default, and is useful to
disable prepared statements. The option is valid for PostgreSQL.
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_server: Host
A hostname or an IP address of the SQL server. The
default value is localhost.
Note about the next option: improved in 20.03:
sql_ssl: true | false
Whether to use SSL encrypted connections to the SQL
server. The option is only available for MySQL 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.
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.
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. 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. This allows one, if enabled, to be able to 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.
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.
This section describes options of all ejabberd modules.
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.
This module provides additional administrative commands.
Details for some commands:
•ban-acount: 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.
•pushroster: (and pushroster-all)
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: If you want to put a group
Name with blankspaces, 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 pushroster command:
[{<<"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 using double-quotes and single-quotes:
ejabberdctl srg-create g1 example.org "'Group number 1'" this_is_g1 g1
This module can be used to update existing SQL database from the
default to the new schema. Check the section Default and New Schemas for
details. Please note that only PostgreSQL is supported. When the module is
loaded use update_sql API.
The module has no options.
This module enables configured users to broadcast announcements
and to set the message of the day (MOTD). Configured users can perform these
actions with an XMPP client either using Ad-hoc Commands or sending messages
to specific JIDs.
Note that this module can be resource intensive on large
deployments as it may broadcast a lot of messages. This module should be
disabled for instances of ejabberd with hundreds of thousands users.
The Ad-hoc Commands are listed in the Server Discovery. For this
feature to work, mod_adhoc must be enabled.
The specific JIDs where messages can be sent are listed below. The
first JID in each entry will apply only to the specified virtual host
example.org, while the JID between brackets will apply to all virtual hosts
in ejabberd:
•example.org/announce/all
(example.org/announce/all-hosts/all):: The message is sent to all registered
users. If the user is online and connected to several resources, only the
resource with the highest priority will receive the message. If the registered
user is not connected, the message will be stored offline in assumption that
offline storage (see mod_offline) is enabled.
•example.org/announce/online
(example.org/announce/all-hosts/online):: The message is sent to all connected
users. If the user is online and connected to several resources, all resources
will receive the message.
•example.org/announce/motd
(example.org/announce/all-hosts/motd):: The message is set as the message of
the day (MOTD) and is sent to users when they login. In addition the message
is sent to all connected users (similar to announce/online).
•example.org/announce/motd/update
(example.org/announce/all-hosts/motd/update):: The message is set as message
of the day (MOTD) and is sent to users when they login. The message is not
sent to any currently connected user.
•example.org/announce/motd/delete
(example.org/announce/all-hosts/motd/delete):: Any message sent to this JID
removes the existing message of the day (MOTD).
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.
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.
This module allows one to block/log 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 ACL where deny means the message will be rejected (or a
CAPTCHA would be generated for a presence, if 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 or not in response to
messages from strangers. See also section 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.
The module implements XEP-0191: Blocking Command.
This module depends on mod_privacy where all the
configuration is performed.
The module has no options.
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: {}
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.
The module implements XEP-0280: Message Carbons. The module
broadcasts messages on all connected user resources (devices).
The module has no options.
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.
The module provides server configuration functionality via
XEP-0050: Ad-Hoc Commands. This module requires mod_adhoc to be
loaded.
The module has no options.
This module serves a simple page for the Converse XMPP web browser
client.
This module is available since ejabberd 21.12. Several options
were improved in ejabberd 22.05.
To use this module, in addition to adding it to the modules
section, you must also enable it in listen →
ejabberd_http → request_handlers.
Make sure either mod_bosh or ejabberd_http_ws
request_handlers are enabled.
When conversejs_css and conversejs_script are
auto, by default they point to the public Converse client.
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.
Note about the next option: added in 22.05:
conversejs_options: {Name: Value}
Specify additional options to be passed to Converse. See
Converse configuration. Only boolean, integer and string values are supported;
lists are not supported.
Note about the next option: added in 22.05:
conversejs_resources: Path
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
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.
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-9.0.0/package/dist"
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
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
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
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.
This module serves small host-meta files as described in
XEP-0156: Discovering Alternative XMPP Connection Methods.
This module is available since ejabberd 22.05.
To use this module, in addition to adding it to the modules
section, you must also enable it in listen →
ejabberd_http → request_handlers.
Notice it only works if ejabberd_http has 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
/ws: ejabberd_http_ws
/.well-known/host-meta: mod_host_meta
/.well-known/host-meta.json: mod_host_meta
modules:
mod_bosh: {}
mod_host_meta:
bosh_service_url: "https://@HOST@:5443/bosh"
websocket_url: "wss://@HOST@:5443/ws"
This module provides a ReST interface to call 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 → 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>
The module has no options.
Example:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/api: mod_http_api
modules:
mod_http_api: {}
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:
.css: text/css
.gif: image/gif
.html: text/html
.jar: application/java-archive
.jpeg: image/jpeg
.jpg: image/jpeg
.js: text/javascript
.png: image/png
.svg: image/svg+xml
.txt: text/plain
.xml: application/xml
.xpi: application/x-xpinstall
.xul: application/vnd.mozilla.xul+xml
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: Path
Directory to serve the files from. This is a mandatory
option.
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/archive/. 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/archive: 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
...
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 → 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.
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 in the Implementation section. 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 mod_http_upload, 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. This will
only be displayed by special XMPP clients. The default value is "HTTP
File Upload".
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. 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 <thumbnail/>
element that contains the download <uri/> 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.
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'>
<FN>Conferences</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
will be 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"
...
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
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:
Please note that 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
...
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.
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.
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.
This module implements XEP-0313: Message Archive Management.
Compatible XMPP clients can use it to store their chat history on the
server.
Available options:
access_preferences: AccessName
This access rule defines who is allowed to modify the MAM
preferences. The default value is all.
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 separa 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.
This module sends events to external backend (by now only grapherl
is supported). Supported events are:
•sm_register_connection
•sm_remove_connection
•user_send_packet
•user_receive_packet
•s2s_send_packet
•s2s_receive_packet
•register_user
•remove_user
•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.
This module is an experimental implementation of XEP-0369:
Mediated Information eXchange (MIX). MIX support was added in ejabberd 16.03
as an experimental feature, updated in 19.02, and is not yet ready to use in
production. 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: Getting started with XEP-0369: Mediated Information eXchange (MIX)
v0.1.
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.
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.
This module adds 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.
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: {publish: [TopicPairs, subscribe:
[TopicPairs], authentication: [AuthInfo]}}]
Declaration of data to share, must contain publish
or subscribe or both, and authentication section with
username/password field or certfile pointing to client certifcate. Accepted
urls can use schema mqtt, mqtts (mqtt with tls), mqtt5, mqtt5s (both to
trigger v5 protocol), ws, wss, ws5, wss5. Certificate authentication can be
only used with mqtts, mqtt5s, wss, wss5.
Example:
modules:
...
mod_mqtt_bridge:
servers:
"mqtt://server.com":
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
authentication:
certfile: "/etc/ejabberd/mqtt_server.pem"
replication_user: "mqtt@xmpp.server.com"
...
This module provides support for XEP-0045: Multi-User Chat. Users
can discover existing rooms, join or create them. Occupants of a room can
chat in public or have private chats.
The MUC service allows any Jabber ID to register a nickname, so
nobody else can use that nickname in any room in the MUC service. To
register a nickname, open the Service Discovery in your XMPP client and
register in the MUC service.
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
This option specifies who is allowed to register nickname
within the Multi-User Chat service. The default is all for backward
compatibility, which means that any user is allowed to register any free
nick.
Note about the next option: added in 22.05:
cleanup_affiliations_on_start: true | false
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.
Note about the next option: improved in 22.05:
default_room_options: Options
This option allows one to define the desired 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: true | false
Occupants can send private messages to other occupants.
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
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.
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 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
Allow extended roles as defined in XEP-0317 Hats. The
default value is false.
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: [moderator | participant | visitor,
...]
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.
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.
Note about the next option: added in 21.01:
max_captcha_whitelist: Number
This option defines the maximum number of characters that
Captcha Whitelist can have when configuring the room. The default value is
infinity.
Note about the next option: added in 21.01:
max_password: Number
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 overcrowed, 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.
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'>
<FN>Conferences</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
will be translated to:
vcard:
fn: Conferences
adr:
-
work: true
street: Elm Street
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:
Note about the next option: added in 22.05:
subscribe_room_many_max_users: Number
How many users can be subscribed to a room at once using
the subscribe_room_many command. The default value is 50.
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:
•Room details are added on top of each page: room
title, JID, author, subject and configuration.
•The room JID in the generated HTML is a link to
join the room (using XMPP URI).
•Subject and room configuration changes are
tracked and displayed.
•Joins, leaves, nick changes, kicks, bans and
/me are tracked and displayed, including the reason if available.
•Generated HTML files are XHTML 1.0 Transitional
and CSS compliant.
•Timestamps are self-referencing links.
•Links on top for quicker navigation: Previous
day, Next day, Up.
•CSS is used for style definition, and a custom
CSS file can be used.
•URLs on messages and subjects are converted to
hyperlinks.
•Timezone used on timestamps is shown on the log
files.
•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
Allows one to 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:
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.
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. The default value
is multicast.@HOST@.
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:
•sender can be: local or
remote.
•stanza can be: message or
presence.
•
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
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.
Note
ejabberdctl has a command to delete expired messages (see
chapter Managing an ejabberd server in online documentation.
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 <resource-constraint/> 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 optimisation 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 optimisation 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
<body/> element. The default value is unless_chat_state, which
tells ejabberd to store messages even if they lack the <body/> element,
unless they only contain a chat state notification (as defined in XEP-0085:
Chat State Notifications.
store_groupchat: true | false
Whether or not to store groupchat messages. The default
value is false.
use_cache: true | false
Same as top-level use_cache option, but applied to
this module only.
use_mam_for_storage: true | false
This is an experimental option. Enabling this option,
mod_offline uses the mod_mam archive table instead of its own
spool table to retrieve the messages received when the user was offline. This
allows client developers to slowly drop XEP-0160 and rely on XEP-0313 instead.
It also further reduces the storage required when you enable MucSub. Enabling
this option has a known drawback for the moment: most of flexible message
retrieval queries don’t work (those that allow retrieval/deletion of
messages by id), but this specification is not widely used. The default value
is false to keep former behaviour as default.
Examples:
This example allows power users to have as much as 5000 offline
messages, administrators up to 2000, and all the other users up to 100:
acl:
admin:
user:
- admin1@localhost
- admin2@example.org
poweruser:
user:
- bob@example.org
- jane@example.org
shaper_rules:
max_user_offline_messages:
- 5000: poweruser
- 2000: admin
- 100
modules:
...
mod_offline:
access_max_user_messages: max_user_offline_messages
...
This module implements support for XEP-0199: XMPP Ping and
periodic keepalives. When this module is enabled ejabberd responds correctly
to ping requests, as defined by the protocol.
Available options:
ping_ack_timeout: timeout()
How long to wait before deeming that a client has not
answered a given server ping request. The default value is
undefined.
ping_interval: timeout()
How often to send pings to connected clients, if option
send_pings is set to true. If a client connection does not send
or receive any stanza within this interval, a ping request is sent to the
client. The default value is 1 minute.
send_pings: true | false
If this option is set to true, the server sends
pings to connected clients that are not active in a given interval defined in
ping_interval option. This is useful to keep client connections alive
or checking availability. The default value is false.
timeout_action: none | kill
What to do when a client does not answer to a server ping
request in less than period defined in ping_ack_timeout option:
kill means destroying the underlying connection, none means to
do nothing. NOTE: when mod_stream_mgmt is loaded and stream management
is enabled by a client, killing the client connection doesn’t mean
killing the client session - the session will be kept alive in order to give
the client a chance to resume it. The default value is none.
Example:
modules:
...
mod_ping:
send_pings: true
ping_interval: 4 min
timeout_action: kill
...
This module detects flood/spam in presence subscriptions traffic.
If a user sends or receives more of those stanzas in a given time interval,
the exceeding stanzas are silently dropped, and a warning is logged.
Available options:
count: Number
The number of subscription presence stanzas (subscribe,
unsubscribe, subscribed, unsubscribed) allowed for any direction (input or
output) per time defined in interval option. Please note that two users
subscribing to each other usually generate 4 stanzas, so the recommended value
is 4 or more. The default value is 5.
interval: timeout()
The time interval. The default value is 1
minute.
Example:
modules:
...
mod_pres_counter:
count: 5
interval: 30 secs
...
This module implements XEP-0016: Privacy Lists.
Note
Nowadays modern XMPP clients rely on XEP-0191: Blocking Command
which is implemented by mod_blocking module. However, you still need
mod_privacy loaded in order for mod_blocking to work.
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.
This module adds support for XEP-0049: Private XML Storage.
Using this method, XMPP entities can store private data on the
server, retrieve it whenever necessary and share it between multiple
connected clients of the same user. The data stored might be anything, as
long as it is a valid XML. One typical usage is storing a bookmark of all
user’s conferences (XEP-0048: Bookmarks).
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.
This module is an implementation of XEP-0356: Privileged Entity.
This extension allows components to have privileged access to other entity
data (send messages on behalf of the server or on behalf of a user, get/set
user roster, access presence information, etc.). This may be used to write
powerful external components, for example implementing an external PEP or
MAM service.
By default a component does not have any privileged access. It is
worth noting that the permissions grant access to the component to a
specific data type for all users of the virtual host on which
mod_privilege is loaded.
Make sure you have a listener configured to connect your
component. Check the section about listening ports for more information.
Warning
Security issue: Privileged access gives components access to
sensitive data, so permission should be granted carefully, only if you trust
a component.
Note
This module is complementary to mod_delegation, but can
also be used separately.
Available options:
message: Options
This option defines permissions for messages. By default
no permissions are given. The
Options are:
outgoing: AccessName
The option defines an access rule for sending outgoing
messages by the component. The default value is none.
presence: Options
This option defines permissions for presences. By default
no permissions are given. The
Options are:
managed_entity: AccessName
An access rule that gives permissions to the component to
receive server presences. The default value is none.
roster: AccessName
An access rule that gives permissions to the component to
receive the presence of both the users and the contacts in their roster. The
default value is none.
roster: Options
This option defines roster permissions. By default no
permissions are given. The
Options are:
both: AccessName
Sets read/write access to a user’s roster. The
default value is none.
get: AccessName
Sets read access to a user’s roster. The default
value is none.
set: AccessName
Sets write access to a user’s roster. The default
value is none.
Example:
modules:
...
mod_privilege:
roster:
get: all
presence:
managed_entity: all
message:
outgoing: all
...
This module implements XEP-0065: SOCKS5 Bytestreams. It allows
ejabberd to act as a file transfer proxy between two XMPP clients.
Available options:
access: AccessName
Defines an access rule for file transfer initiators. The
default value is all. You may want to restrict access to the users of
your server only, in order to avoid abusing your proxy by the users of remote
servers.
auth_type: anonymous | plain
SOCKS5 authentication type. The default value is
anonymous. If set to plain, ejabberd will use authentication
backend as it would for SASL PLAIN.
host
Deprecated. Use hosts instead.
hostname: Host
Defines a hostname offered by the proxy when establishing
a session with clients. This is useful when you run the proxy behind a NAT.
The keyword @HOST@ is replaced with the virtual host name. The default
is to use the value of ip option. Examples: proxy.mydomain.org,
200.150.100.50.
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 "proxy.". The keyword
@HOST@ is replaced with the real virtual host name.
ip: IPAddress
This option specifies which network interface to listen
for. The default value is an IP address of the service’s DNS name, or,
if fails, 127.0.0.1.
max_connections: pos_integer() | infinity
Maximum number of active connections per file transfer
initiator. The default value is infinity.
name: Name
The value of the service name. This name is only visible
in some clients that support XEP-0030: Service Discovery. The default is
"SOCKS5 Bytestreams".
port: 1..65535
A port number to listen for incoming connections. The
default value is 7777.
ram_db_type: mnesia | redis | sql
Same as top-level default_ram_db option, but
applied to this module only.
recbuf: Size
A size of the buffer for incoming packets. If you define
a shaper, set the value of this option to the size of the shaper in order to
avoid traffic spikes in file transfers. The default value is 65536
bytes.
shaper: Shaper
This option defines a shaper for the file transfer peers.
A shaper with the maximum bandwidth will be selected. The default is
none, i.e. no shaper.
sndbuf: Size
A size of the buffer for outgoing packets. If you define
a shaper, set the value of this option to the size of the shaper in order to
avoid traffic spikes in file transfers. The default value is 65536
bytes.
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.
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'>
<FN>Conferences</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
will be translated to:
vcard:
fn: Conferences
adr:
-
work: true
street: Elm Street
Example:
acl:
admin:
user: admin@example.org
proxy_users:
server: example.org
access_rules:
proxy65_access:
allow: proxy_users
shaper_rules:
proxy65_shaper:
none: admin
proxyrate: proxy_users
shaper:
proxyrate: 10240
modules:
...
mod_proxy65:
host: proxy1.example.org
name: "File Transfer Proxy"
ip: 200.150.100.1
port: 7778
max_connections: 5
access: proxy65_access
shaper: proxy65_shaper
recbuf: 10240
sndbuf: 10240
...
This module offers a service for XEP-0060: Publish-Subscribe. The
functionality in mod_pubsub can be extended using plugins. The plugin
that implements PEP (XEP-0163: Personal Eventing via Pubsub) is enabled in
the default ejabberd configuration file, and it requires
mod_caps.
Available options:
access_createnode: AccessName
This option restricts which users are allowed to create
pubsub nodes using acl and access. By default any account in the
local ejabberd server is allowed to create pubsub nodes. The default value is:
all.
db_type: mnesia | sql
Same as top-level default_db option, but applied
to this module only.
default_node_config: List of Key:Value
To override default node configuration, regardless of
node plugin. Value is a list of key-value definition. Node configuration still
uses default configuration defined by node plugin, and overrides any items by
value defined in this configurable list.
force_node_config: List of Node and the list of its
Key:Value
Define the configuration for given nodes. The default
value is:
[].
Example:
force_node_config:
## Avoid buggy clients to make their bookmarks public
storage:bookmarks:
access_model: whitelist
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 "pubsub.". The keyword
@HOST@ is replaced with the real virtual host name.
ignore_pep_from_offline: false | true
To specify whether or not we should get last published
PEP items from users in our roster which are offline when we connect. Value is
true or false. If not defined, pubsub assumes true so we only
get last items of online contacts.
last_item_cache: false | true
To specify whether or not pubsub should cache last items.
Value is true or false. If not defined, pubsub does not cache
last items. On systems with not so many nodes, caching last items speeds up
pubsub and allows one to raise user connection rate. The cost is memory usage,
as every item is stored in memory.
Note about the next option: added in 21.12:
max_item_expire_node: timeout() | infinity
Specify the maximum item epiry time. Default value is:
infinity.
max_items_node: non_neg_integer() | infinity
Define the maximum number of items that can be stored in
a node. Default value is: 1000.
max_nodes_discoitems: pos_integer() | infinity
The maximum number of nodes to return in a discoitem
response. The default value is: 100.
max_subscriptions_node: MaxSubs
Define the maximum number of subscriptions managed by a
node. Default value is no limitation: undefined.
name: Name
The value of the service name. This name is only visible
in some clients that support XEP-0030: Service Discovery. The default is
vCard User Search.
nodetree: Nodetree
To specify which nodetree to use. If not defined, the
default pubsub nodetree is used:
tree. Only one nodetree can be used
per host, and is shared by all node plugins.
•tree nodetree store node configuration and
relations on the database. flat nodes are stored without any
relationship, and hometree nodes can have child nodes.
•virtual nodetree does not store nodes on
database. This saves resources on systems with tons of nodes. If using the
virtual nodetree, you can only enable those node plugins: [flat,
pep] or [flat]; any other plugins configuration will not work.
Also, all nodes will have the default configuration, and this can not be
changed. Using virtual nodetree requires to start from a clean
database, it will not work if you used the default tree nodetree
before.
pep_mapping: List of Key:Value
This allows one to define a list of key-value to choose
defined node plugins on given PEP namespace. The following example will use
node_tune instead of
node_pep for every PEP node with the tune
namespace:
Example:
modules:
...
mod_pubsub:
pep_mapping:
http://jabber.org/protocol/tune: tune
...
plugins: [Plugin, ...]
To specify which pubsub node plugins to use. The first
one in the list is used by default. If this option is not defined, the default
plugins list is:
[flat]. PubSub clients can define which plugin to use
when creating a node: add
type='plugin-name' attribute to the
create stanza element.
•flat plugin handles the default behaviour
and follows standard XEP-0060 implementation.
•pep plugin adds extension to handle
Personal Eventing Protocol (XEP-0163) to the PubSub engine. Adding pep allows
one to handle PEP automatically.
vcard: vCard
A custom vCard of the server 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.
The following XML representation of vCard:
<vCard xmlns='vcard-temp'>
<FN>PubSub Service</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
will be translated to:
vcard:
fn: PubSub Service
adr:
-
work: true
street: Elm Street
Examples:
Example of configuration that uses flat nodes as default, and
allows use of flat, hometree and pep nodes:
modules:
...
mod_pubsub:
access_createnode: pubsub_createnode
max_subscriptions_node: 100
default_node_config:
notification_type: normal
notify_retract: false
max_items: 4
plugins:
- flat
- pep
...
Using relational database requires using mod_pubsub with db_type
sql. Only flat, hometree and pep plugins supports SQL. The following
example shows previous configuration with SQL usage:
modules:
...
mod_pubsub:
db_type: sql
access_createnode: pubsub_createnode
ignore_pep_from_offline: true
last_item_cache: false
plugins:
- flat
- pep
...
This module implements the XMPP server’s part of the push
notification solution specified in XEP-0357: Push Notifications. It does not
generate, for example, APNS or FCM notifications directly. Instead,
it’s designed to work with so-called "app servers" operated
by third-party vendors of mobile apps. Those app servers will usually
trigger notification delivery to the user’s mobile device using
platform-dependant backend services such as FCM or APNS.
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.
include_body: true | false | Text
If this option is set to true, the message text is
included with push notifications generated for incoming messages with a body.
The option can instead be set to a static Text, in which case the
specified text will be included in place of the actual message body. This can
be useful to signal the app server whether the notification was triggered by a
message with body (as opposed to other types of traffic) without leaking
actual message contents. The default value is "New message".
include_sender: true | false
If this option is set to true, the sender’s
JID is included with push notifications generated for incoming messages with a
body. The default value is false.
use_cache: true | false
Same as top-level use_cache option, but applied to
this module only.
This module tries to keep the stream management session (see
mod_stream_mgmt) of a disconnected mobile client alive if the client
enabled push notifications for that session. However, the normal session
resumption timeout is restored once a push notification is issued, so the
session will be closed if the client doesn’t respond to push
notifications.
The module depends on mod_push.
Available options:
resume_timeout: timeout()
This option specifies the period of time until the
session of a disconnected push client times out. This timeout is only in
effect as long as no push notification is issued. Once that happened, the
resumption timeout configured for mod_stream_mgmt is restored. The
default value is 72 hours.
wake_on_start: true | false
If this option is set to true, notifications are
generated for all registered push clients during server startup. This
option should not be enabled on servers with many push clients as it can
generate significant load on the involved push services and the server itself.
The default value is false.
wake_on_timeout: true | false
If this option is set to true, a notification is
generated shortly before the session would time out as per the
resume_timeout option. The default value is true.
This module adds support for XEP-0077: In-Band Registration. This
protocol enables end users to use an XMPP client to:
•Register a new account on the server.
•Change the password from an existing account on
the server.
•Delete an existing account on the server.
This module reads also the top-level registration_timeout
option defined globally for the server, so please check that option
documentation too.
Available options:
access: AccessName
Specify rules to restrict what usernames can be
registered. If a rule returns deny on the requested username,
registration of that user name is denied. There are no restrictions by
default.
access_from: AccessName
By default, ejabberd doesn’t allow one to
register new accounts from s2s or existing c2s sessions. You can change it by
defining access rule in this option. Use with care: allowing registration from
s2s leads to uncontrolled massive accounts creation by rogue users.
access_remove: AccessName
Specify rules to restrict access for user unregistration.
By default any user is able to unregister their account.
Note about the next option: added in 21.12:
allow_modules: all | [Module, ...]
List of modules that can register accounts, or
all. The default value is all, which is equivalent to something
like [mod_register, mod_register_web].
captcha_protected: true | false
Protect registrations with CAPTCHA. The default is
false.
ip_access: AccessName
Define rules to allow or deny account registration
depending on the IP address of the XMPP client. The AccessName should
be of type ip. The default value is all.
password_strength: Entropy
This option sets the minimum Shannon entropy for
passwords. The value Entropy is a number of bits of entropy. The
recommended minimum is 32 bits. The default is 0, i.e. no checks are
performed.
redirect_url: URL
This option enables registration redirection as described
in XEP-0077: In-Band Registration: Redirection.
registration_watchers: [JID, ...]
This option defines a list of JIDs which will be notified
each time a new account is registered.
welcome_message: {subject: Subject, body: Body}
Set a welcome message that is sent to each newly
registered account. The message will have subject Subject and text
Body.
This module provides a web page where users can:
•Register a new account on the server.
•Change the password from an existing account on
the server.
•Unregister an existing account on the
server.
This module supports CAPTCHA to register a new account. To enable
this feature, configure the top-level captcha_cmd and top-level
captcha_url options.
As an example usage, the users of the host localhost can
visit the page: https://localhost:5280/register/ It is important to
include the last / character in the URL, otherwise the subpages URL will be
incorrect.
This module is enabled in listen →
ejabberd_http → request_handlers, no need to enable in
modules. The module depends on mod_register where all the
configuration is performed.
The module has no options.
Example:
listen:
-
port: 5280
module: ejabberd_http
request_handlers:
/register: mod_register_web
modules:
mod_register: {}
This module implements roster management as defined in RFC6121
Section 2. The module also adds support for XEP-0237: Roster Versioning.
Available options:
access: AccessName
This option can be configured to specify rules to
restrict roster management. If the rule returns deny on the requested
user name, that user cannot modify their personal roster, i.e. they cannot
add/remove/modify contacts or send presence subscriptions. The default value
is all, i.e. 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.
store_current_id: true | false
If this option is set to true, the current roster
version number is stored on the database. If set to false, the roster
version number is calculated on the fly each time. Enabling this option
reduces the load for both ejabberd and the database. This option does not
affect the client in any way. This option is only useful if option
versioning is set to true. The default value is false.
IMPORTANT: if you use mod_shared_roster or
mod_shared_roster_ldap, you must set the value of the option to
false.
use_cache: true | false
Same as top-level use_cache option, but applied to
this module only.
versioning: true | false
Enables/disables Roster Versioning. The default value is
false.
Example:
modules:
...
mod_roster:
versioning: true
store_current_id: false
...
The module adds support for XEP-0220: Server Dialback to provide
server identity verification based on DNS.
Warning
DNS-based verification is vulnerable to DNS cache poisoning, so
modern servers rely on verification based on PKIX certificates. Thus this
module is only recommended for backward compatibility with servers running
outdated software or non-TLS servers, or those with invalid certificates (as
long as you accept the risks, e.g. you assume that the remote server has an
invalid certificate due to poor administration and not because it’s
compromised).
Available options:
access: AccessName
An access rule that can be used to restrict dialback for
some servers. The default value is all.
Example:
modules:
...
mod_s2s_dialback:
access:
allow:
server: legacy.domain.tld
server: invalid-cert.example.org
deny: all
...
This module forwards copies of all stanzas to remote XMPP servers
or components. Every stanza is encapsulated into <forwarded/> element
as described in XEP-0297: Stanza Forwarding.
Available options:
loggers: [Domain, ...]
A list of servers or connected components to which
stanzas will be forwarded.
Example:
modules:
...
mod_service_log:
loggers:
- xmpp-server.tld
- component.domain.tld
...
This module enables you to create shared roster groups: groups of
accounts that can see members from (other) groups in their rosters.
The big advantages of this feature are that end users do not need
to manually add all users to their rosters, and that they cannot permanently
delete users from the shared roster groups. A shared roster group can have
members from any XMPP server, but the presence will only be available from
and to members of the same virtual host where the group is created. It still
allows the users to have / add their own contacts, as it does not replace
the standard roster. Instead, the shared roster contacts are merged to the
relevant users at retrieval time. The standard user rosters thus stay
unmodified.
Shared roster groups can be edited via the Web Admin, and some API
commands called srg_*. Each group has a unique name and those
parameters:
•Label: Used in the rosters where this group is
displayed.
•Description: of the group, which has no
effect.
•Members: A list of JIDs of group members, entered
one per line in the Web Admin. The special member directive @all@
represents all the registered users in the virtual host; which is only
recommended for a small server with just a few hundred users. The special
member directive @online@ represents the online users in the virtual
host. With those two directives, the actual list of members in those shared
rosters is generated dynamically at retrieval time.
•Displayed: A list of groups that will be in the
rosters of this group’s members. A group of other vhost can be
identified with groupid@vhost.
This module depends on mod_roster. If not enabled, roster
queries will return 503 errors.
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.
Examples:
Take the case of a computer club that wants all its members seeing
each other in their rosters. To achieve this, they need to create a shared
roster group similar to this one:
Name: club_members
Label: Club Members
Description: Members from the computer club
Members: member1@example.org, member2@example.org, member3@example.org
Displayed Groups: club_members
In another case we have a company which has three divisions:
Management, Marketing and Sales. All group members should see all other
members in their rosters. Additionally, all managers should have all
marketing and sales people in their roster. Simultaneously, all marketeers
and the whole sales team should see all managers. This scenario can be
achieved by creating shared roster groups as shown in the following
lists:
First list:
Name: management
Label: Management
Description: Management
Members: manager1@example.org, manager2@example.org
Displayed: management, marketing, sales
Second list:
Name: marketing
Label: Marketing
Description: Marketing
Members: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org
Displayed: management, marketing
Third list:
Name: sales
Label: Sales
Description: Sales
Members: salesman1@example.org, salesman2@example.org, salesman3@example.org
Displayed: management, sales
This module lets the server administrator automatically populate
users' rosters (contact lists) with entries based on users and groups
defined in an LDAP-based directory.
Note
mod_shared_roster_ldap depends on mod_roster being
enabled. Roster queries will return 503 errors if mod_roster
is not enabled.
The module accepts many configuration options. Some of them, if
unspecified, default to the values specified for the top level of
configuration. This lets you avoid specifying, for example, the bind
password in multiple places.
•Filters: ldap_rfilter,
ldap_ufilter, ldap_gfilter, ldap_filter. These options
specify LDAP filters used to query for shared roster information. All of them
are run against the ldap_base.
•Attributes: ldap_groupattr,
ldap_groupdesc, ldap_memberattr, ldap_userdesc,
ldap_useruid. These options specify the names of the attributes which
hold interesting data in the entries returned by running filters specified
with the filter options.
•Control parameters: ldap_auth_check,
ldap_group_cache_validity, ldap_memberattr_format,
ldap_memberattr_format_re, ldap_user_cache_validity. These
parameters control the behaviour of the module.
•Connection parameters: The module also accepts
the connection parameters, all of which default to the top-level parameter of
the same name, if unspecified. See LDAP Connection section for more
information about them.
Check also the Configuration examples section to get details about
retrieving the roster, and configuration examples including Flat DIT and
Deep DIT.
Available options:
cache_life_time
Same as top-level cache_life_time option, but
applied to this module only.
cache_missed
Same as top-level cache_missed option, but applied
to this module only.
cache_size
Same as top-level cache_size option, but applied
to this module only.
ldap_auth_check: true | false
Whether the module should check (via the ejabberd
authentication subsystem) for existence of each user in the shared LDAP
roster. Set to false if you want to disable the check. Default value is
true.
ldap_backups
Same as top-level ldap_backups option, but applied
to this module only.
ldap_base
Same as top-level ldap_base option, but applied to
this module only.
ldap_deref_aliases
Same as top-level ldap_deref_aliases option, but
applied to this module only.
ldap_encrypt
Same as top-level ldap_encrypt option, but applied
to this module only.
ldap_filter
Additional filter which is AND-ed together with
"User Filter" and "Group Filter". For more information
check the LDAP Filters section.
ldap_gfilter
"Group Filter", used when retrieving
human-readable name (a.k.a. "Display Name") and the members of a
group. See also the parameters ldap_groupattr, ldap_groupdesc
and ldap_memberattr. If unspecified, defaults to the top-level
parameter of the same name. If that one also is unspecified, then the filter
is constructed exactly like "User Filter".
ldap_groupattr
The name of the attribute that holds the group name, and
that is used to differentiate between them. Retrieved from results of the
"Roster Filter" and "Group Filter". Defaults to
cn.
ldap_groupdesc
The name of the attribute which holds the human-readable
group name in the objects you use to represent groups. Retrieved from results
of the "Group Filter". Defaults to whatever ldap_groupattr is
set.
ldap_memberattr
The name of the attribute which holds the IDs of the
members of a group. Retrieved from results of the "Group Filter".
Defaults to memberUid. The name of the attribute differs depending on
the objectClass you use for your group objects, for example: posixGroup
→ memberUid; groupOfNames → member;
groupOfUniqueNames → uniqueMember.
ldap_memberattr_format
A globbing format for extracting user ID from the value
of the attribute named by ldap_memberattr. Defaults to %u, which
means that the whole value is the member ID. If you change it to something
different, you may also need to specify the User and Group Filters manually;
see section Filters.
ldap_memberattr_format_re
A regex for extracting user ID from the value of the
attribute named by ldap_memberattr. Check the LDAP Control Parameters
section.
ldap_password
Same as top-level ldap_password option, but
applied to this module only.
ldap_port
Same as top-level ldap_port option, but applied to
this module only.
ldap_rfilter
So called "Roster Filter". Used to find names
of all "shared roster" groups. See also the ldap_groupattr
parameter. If unspecified, defaults to the top-level parameter of the same
name. You must specify it in some place in the configuration, there is no
default.
ldap_rootdn
Same as top-level ldap_rootdn option, but applied
to this module only.
ldap_servers
Same as top-level ldap_servers option, but applied
to this module only.
ldap_tls_cacertfile
Same as top-level ldap_tls_cacertfile option, but
applied to this module only.
ldap_tls_certfile
Same as top-level ldap_tls_certfile option, but
applied to this module only.
ldap_tls_depth
Same as top-level ldap_tls_depth option, but
applied to this module only.
ldap_tls_verify
Same as top-level ldap_tls_verify option, but
applied to this module only.
ldap_ufilter
"User Filter", used for retrieving the
human-readable name of roster entries (usually full names of people in the
roster). See also the parameters ldap_userdesc and ldap_useruid.
For more information check the LDAP Filters section.
ldap_uids
Same as top-level ldap_uids option, but applied to
this module only.
ldap_userdesc
The name of the attribute which holds the human-readable
user name. Retrieved from results of the "User Filter". Defaults to
cn.
ldap_userjidattr
The name of the attribute which is used to map user id to
XMPP jid. If not specified (and that is default value of this option), user
jid will be created from user id and this module host.
ldap_useruid
The name of the attribute which holds the ID of a roster
item. Value of this attribute in the roster item objects needs to match the ID
retrieved from the ldap_memberattr attribute of a group object.
Retrieved from results of the "User Filter". Defaults to
cn.
use_cache
Same as top-level use_cache option, but applied to
this module only.
This module adds support for XEP-0279: Server IP Check. This
protocol enables a client to discover its external IP address.
Warning
The protocol extension is deferred and seems like there are no
clients supporting it, so using this module is not recommended and,
furthermore, the module might be removed in the future.
The module has no options.
This module adds SIP proxy/registrar support for the corresponding
virtual host.
Note
It is not enough to just load this module. You should also
configure listeners and DNS records properly. For details see the section
about the ejabberd_sip listen module in the ejabberd Documentation.
Available options:
always_record_route: true | false
Always insert "Record-Route" header into SIP
messages. This approach allows one to bypass NATs/firewalls a bit more easily.
The default value is true.
flow_timeout_tcp: timeout()
The option sets a keep-alive timer for SIP outbound TCP
connections. The default value is 2 minutes.
flow_timeout_udp: timeout()
The options sets a keep-alive timer for SIP outbound UDP
connections. The default value is 29 seconds.
record_route: URI
When the option always_record_route is set to
true or when SIP outbound is utilized, ejabberd inserts
"Record-Route" header field with this URI into a SIP message.
The default is a SIP URI constructed from the virtual host on which the module
is loaded.
routes: [URI, ...]
You can set a list of SIP URIs of routes pointing to this
SIP proxy server. The default is a list containing a single SIP URI
constructed from the virtual host on which the module is loaded.
via: [URI, ...]
A list to construct "Via" headers for inserting
them into outgoing SIP messages. This is useful if you’re running your
SIP proxy in a non-standard network topology. Every URI element in the
list must be in the form of "scheme://host:port", where
"transport" must be tls, tcp, or udp,
"host" must be a domain name or an IP address and "port"
must be an internet port number. Note that all parts of the URI are
mandatory (e.g. you cannot omit "port" or "scheme").
Example:
modules:
...
mod_sip:
always_record_route: false
record_route: "sip:example.com;lr"
routes:
- "sip:example.com;lr"
- "sip:sip.example.com;lr"
flow_timeout_udp: 30 sec
flow_timeout_tcp: 1 min
via:
- tls://sip-tls.example.com:5061
- tcp://sip-tcp.example.com:5060
- udp://sip-udp.example.com:5060
...
This module adds support for XEP-0039: Statistics Gathering. This
protocol allows you to retrieve the following statistics from your ejabberd
server:
•Total number of registered users on the current
virtual host (users/total).
•Total number of registered users on all virtual
hosts (users/all-hosts/total).
•Total number of online users on the current
virtual host (users/online).
•Total number of online users on all virtual hosts
(users/all-hosts/online).
Note
The protocol extension is deferred and seems like even a few
clients that were supporting it are now abandoned. So using this module
makes very little sense.
The module has no options.
This module adds support for XEP-0198: Stream Management. This
protocol allows active management of an XML stream between two XMPP
entities, including features for stanza acknowledgements and stream
resumption.
Available options:
ack_timeout: timeout()
A time to wait for stanza acknowledgements. Setting it to
infinity effectively disables the timeout. The default value is
1 minute.
cache_life_time: timeout()
Same as top-level cache_life_time option, but
applied to this module only. The default value is 48 hours.
cache_size: pos_integer() | infinity
Same as top-level cache_size option, but applied
to this module only.
max_ack_queue: Size
This option specifies the maximum number of
unacknowledged stanzas queued for possible retransmission. When the limit is
exceeded, the client session is terminated. The allowed values are positive
integers and infinity. You should be careful when setting this value as
it should not be set too low, otherwise, you could kill sessions in a loop,
before they get the chance to finish proper session initiation. It should
definitely be set higher that the size of the offline queue (for example at
least 3 times the value of the max offline queue and never lower than
1000). The default value is 5000.
max_resume_timeout: timeout()
A client may specify the period of time until a session
times out if the connection is lost. During this period of time, the client
may resume its session. This option limits the period of time a client is
permitted to request. It must be set to a timeout equal to or larger than the
default resume_timeout. By default, it is set to the same value as the
resume_timeout option.
queue_type: ram | file
Same as top-level queue_type option, but applied
to this module only.
resend_on_timeout: true | false | if_offline
If this option is set to true, any message stanzas
that weren’t acknowledged by the client will be resent on session
timeout. This behavior might often be desired, but could have unexpected
results under certain circumstances. For example, a message that was sent to
two resources might get resent to one of them if the other one timed out.
Therefore, the default value for this option is false, which tells
ejabberd to generate an error message instead. As an alternative, the option
may be set to if_offline. In this case, unacknowledged messages are
resent only if no other resource is online when the session times out.
Otherwise, error messages are generated.
resume_timeout: timeout()
This option configures the (default) period of time until
a session times out if the connection is lost. During this period of time, a
client may resume its session. Note that the client may request a different
timeout value, see the max_resume_timeout option. Setting it to
0 effectively disables session resumption. The default value is
5 minutes.
This module allows XMPP clients to discover STUN/TURN services and
to obtain temporary credentials for using them as per XEP-0215: External
Service Discovery. This module is included in ejabberd since version
20.04.
Available options:
access: AccessName
This option defines which access rule will be used to
control who is allowed to discover STUN/TURN services and to request temporary
credentials. The default value is local.
credentials_lifetime: timeout()
The lifetime of temporary credentials offered to clients.
If ejabberd’s built-in TURN service is used, TURN relays allocated
using temporary credentials will be terminated shortly after the credentials
expired. The default value is 12 hours. Note that restarting the
ejabberd node invalidates any temporary credentials offered before the restart
unless a secret is specified (see below).
offer_local_services: true | false
This option specifies whether local STUN/TURN services
configured as ejabberd listeners should be announced automatically. Note that
this will not include TLS-enabled services, which must be configured manually
using the services option (see below). For non-anonymous TURN services,
temporary credentials will be offered to the client. The default value is
true.
secret: Text
The secret used for generating temporary credentials. If
this option isn’t specified, a secret will be auto-generated. However,
a secret must be specified explicitly if non-anonymous TURN services running
on other ejabberd nodes and/or external TURN services are configured.
Also note that auto-generated secrets are lost when the node is restarted,
which invalidates any credentials offered before the restart. Therefore,
it’s recommended to explicitly specify a secret if clients cache
retrieved credentials (for later use) across service restarts.
services: [Service, ...]
The list of services offered to clients. This list can
include STUN/TURN services running on any ejabberd node and/or external
services. However, if any listed TURN service not running on the local
ejabberd node requires authentication, a
secret must be specified
explicitly, and must be shared with that service. This will only work with
ejabberd’s built-in STUN/TURN server and with external servers that
support the same REST API For Access To TURN Services. Unless the
offer_local_services is set to
false, the explicitly listed
services will be offered in addition to those announced automatically.
host: Host
The hostname or IP address the STUN/TURN service is
listening on. For non-TLS services, it’s recommended to specify an IP
address (to avoid additional DNS lookup latency on the client side). For TLS
services, the hostname (or IP address) should match the certificate.
Specifying the host option is mandatory.
port: 1..65535
The port number the STUN/TURN service is listening on.
The default port number is 3478 for non-TLS services and 5349 for TLS
services.
restricted: true | false
This option determines whether temporary credentials for
accessing the service are offered. The default is false for STUN/STUNS
services and true for TURN/TURNS services.
transport: tcp | udp
The transport protocol supported by the service. The
default is udp for non-TLS services and tcp for TLS
services.
type: stun | turn | stuns | turns
The type of service. Must be stun or turn
for non-TLS services, stuns or turns for TLS services. The
default type is stun.
Example:
services:
-
host: 203.0.113.3
port: 3478
type: stun
transport: udp
restricted: false
-
host: 203.0.113.3
port: 3478
type: turn
transport: udp
restricted: true
-
host: 2001:db8::3
port: 3478
type: stun
transport: udp
restricted: false
-
host: 2001:db8::3
port: 3478
type: turn
transport: udp
restricted: true
-
host: server.example.com
port: 5349
type: turns
transport: tcp
restricted: true
This module adds support for XEP-0202: Entity Time. In other
words, the module reports server’s system time.
The module has no options.
This module allows end users to store and retrieve their vCard,
and to retrieve other users vCards, as defined in XEP-0054: vcard-temp. The
module also implements an uncomplicated Jabber User Directory based on the
vCards of these users. Moreover, it enables the server to send its vCard
when queried.
Available options:
allow_return_all: true | false
This option enables you to specify if search operations
with empty input fields should return all users who added some information to
their vCard. The default value is 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.
db_type: mnesia | sql | ldap
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 "vjud.". The keyword
@HOST@ is replaced with the real virtual host name.
matches: pos_integer() | infinity
With this option, the number of reported search results
can be limited. If the option’s value is set to infinity, all
search results are reported. The default value is 30.
name: Name
The value of the service name. This name is only visible
in some clients that support XEP-0030: Service Discovery. The default is
vCard User Search.
search: true | false
This option specifies whether the search functionality is
enabled or not. If disabled, the options hosts, name and
vcard will be ignored and the Jabber User Directory service will not
appear in the Service Discovery item list. The default value is
false.
use_cache: true | false
Same as top-level use_cache option, but applied to
this module only.
vcard: vCard
A custom vCard of the server 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.
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'>
<FN>Conferences</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
will be translated to:
vcard:
fn: Conferences
adr:
-
work: true
street: Elm Street
Available options for ldap backend:
ldap_backups
Same as top-level ldap_backups option, but applied
to this module only.
ldap_base
Same as top-level ldap_base option, but applied to
this module only.
ldap_deref_aliases
Same as top-level ldap_deref_aliases option, but
applied to this module only.
ldap_encrypt
Same as top-level ldap_encrypt option, but applied
to this module only.
ldap_filter
Same as top-level ldap_filter option, but applied
to this module only.
ldap_password
Same as top-level ldap_password option, but
applied to this module only.
ldap_port
Same as top-level ldap_port option, but applied to
this module only.
ldap_rootdn
Same as top-level ldap_rootdn option, but applied
to this module only.
ldap_search_fields: {Name: Attribute, ...}
This option defines the search form and the LDAP
attributes to search within.
Name is the name of a search form field
which will be automatically translated by using the translation files (see
msgs/*.msg for available words).
Attribute is the LDAP attribute
or the pattern
%u.
The default is:
User: "%u"
"Full Name": displayName
"Given Name": givenName
"Middle Name": initials
"Family Name": sn
Nickname: "%u"
Birthday: birthDay
Country: c
City: l
Email: mail
"Organization Name": o
"Organization Unit": ou
ldap_search_reported: {SearchField: VcardField},
...}
This option defines which search fields should be
reported.
SearchField is the name of a search form field which will be
automatically translated by using the translation files (see
msgs/*.msg
for available words).
VcardField is the vCard field name defined in the
ldap_vcard_map option.
The default is:
"Full Name": FN
"Given Name": FIRST
"Middle Name": MIDDLE
"Family Name": LAST
"Nickname": NICKNAME
"Birthday": BDAY
"Country": CTRY
"City": LOCALITY
"Email": EMAIL
"Organization Name": ORGNAME
"Organization Unit": ORGUNIT
ldap_servers
Same as top-level ldap_servers option, but applied
to this module only.
ldap_tls_cacertfile
Same as top-level ldap_tls_cacertfile option, but
applied to this module only.
ldap_tls_certfile
Same as top-level ldap_tls_certfile option, but
applied to this module only.
ldap_tls_depth
Same as top-level ldap_tls_depth option, but
applied to this module only.
ldap_tls_verify
Same as top-level ldap_tls_verify option, but
applied to this module only.
ldap_uids
Same as top-level ldap_uids option, but applied to
this module only.
ldap_vcard_map: {Name: {Pattern, LDAPattributes},
...}
With this option you can set the table that maps LDAP
attributes to vCard fields.
Name is the type name of the vCard as
defined in RFC 2426.
Pattern is a string which contains pattern
variables
%u,
%d or
%s.
LDAPattributes is the list
containing LDAP attributes. The pattern variables
%s will be
sequentially replaced with the values of LDAP attributes from
List_of_LDAP_attributes,
%u will be replaced with the user part
of a JID, and
%d will be replaced with the domain part of a JID.
The default is:
NICKNAME: {"%u": []}
FN: {"%s": [displayName]}
LAST: {"%s": [sn]}
FIRST: {"%s": [givenName]}
MIDDLE: {"%s": [initials]}
ORGNAME: {"%s": [o]}
ORGUNIT: {"%s": [ou]}
CTRY: {"%s": [c]}
LOCALITY: {"%s": [l]}
STREET: {"%s": [street]}
REGION: {"%s": [st]}
PCODE: {"%s": [postalCode]}
TITLE: {"%s": [title]}
URL: {"%s": [labeleduri]}
DESC: {"%s": [description]}
TEL: {"%s": [telephoneNumber]}
EMAIL: {"%s": [mail]}
BDAY: {"%s": [birthDay]}
ROLE: {"%s": [employeeType]}
PHOTO: {"%s": [jpegPhoto]}
Available options for mnesia backend:
search_all_hosts: true | false
Whether to perform search on all virtual hosts or not.
The default value is true.
The user’s client can store an avatar in the user vCard.
The vCard-Based Avatars protocol (XEP-0153) provides a method for clients to
inform the contacts what is the avatar hash value. However, simple or small
clients may not implement that protocol.
If this module is enabled, all the outgoing client presence
stanzas get automatically the avatar hash on behalf of the client. So, the
contacts receive the presence stanzas with the Update Data described
in XEP-0153 as if the client would had inserted it itself. If the client had
already included such element in the presence stanza, it is replaced with
the element generated by ejabberd.
By enabling this module, each vCard modification produces a hash
recalculation, and each presence sent by a client produces hash retrieval
and a presence stanza rewrite. For this reason, enabling this module will
introduce a computational overhead in servers with clients that change
frequently their presence. However, the overhead is significantly reduced by
the use of caching, so you probably don’t want to set
use_cache to false.
The module depends on mod_vcard.
Note
Nowadays XEP-0153 is used mostly as "read-only", i.e.
modern clients don’t publish their avatars inside vCards. Thus in the
majority of cases the module is only used along with mod_avatar for
providing backward compatibility.
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.
use_cache: true | false
Same as top-level use_cache option, but applied to
this module only.
This module implements XEP-0092: Software Version. Consequently,
it answers ejabberd’s version when queried.
Available options:
show_os: true | false
Should the operating system be revealed or not. The
default value is true.