EJABBERD.YML(5)

📦

version 26.09.1 · 7 versions

26.09.1 · arch rolling, nixos 26.05, nixpkgs unstable (latest)
26.02 · alpine 3.24
26.02 · ubuntu stonking
21.12 · ubuntu jammy
23.01 · debian bookworm
23.10 · ubuntu noble
24.12 · debian trixie, ubuntu questing, ubuntu resolute

, in arch rolling, nixos 26.05, nixpkgs unstable

🎀 ejabberd.yml(5) — main configuration file for ejabberd 🎀

💖 NAME 💖

ejabberd.yml — main configuration file for ejabberd.

✨ SYNOPSIS ✨

ejabberd.yml

🌸 DESCRIPTION 🌸

Okay so bestie, the configuration file is written in YAML language. That's the vibe.

⚠️ Warning: YAML is indentation sensitive, so make sure you respect indentation, or otherwise you will get pretty cryptic configuration errors. Fr fr, one wrong space and it's giving why is my server crying 😭.

Logically, configuration options are split into 3 main categories: Modules, Listeners and everything else called Top Level options. Thus this document is split into 3 main chapters describing each category separately. So, the contents of ejabberd.yml will typically look like this:

hosts:
  - example.com
  - domain.tld
loglevel: info
...
listen:
  -
    port: 5222
    module: ejabberd_c2s
  ...
modules:
  mod_roster: {}
  ...

Any configuration error (such as syntax error, unknown option or invalid option value) is fatal in the sense that ejabberd will refuse to load the whole configuration file and will not start or will abort configuration reload. Not me being dramatic — that's just the rules 💅.

All options can be changed in runtime by running ejabberdctl reload-config command. Configuration reload is atomic: either all options are accepted and applied simultaneously or the new configuration is refused without any impact on currently running configuration. It's giving all-or-nothing, and honestly? Iconic.

Some options can be specified for particular virtual host(s) only using host_config or append_host_config options. Such options are called local. Examples are modules, auth_method and default_db. The options that cannot be defined per virtual host are called global. Examples are loglevel, certfiles and listen. It is a configuration mistake to put global options under host_config or append_host_config section - ejabberd will refuse to load such configuration. So don't try it, bestie — it's not that girl.

It is not recommended to write ejabberd.yml from scratch. Instead it is better to start from "default" configuration file available at https://github.com/processone/ejabberd/blob/26.09/ejabberd.yml.example. Once you get ejabberd running you can start changing configuration options to meet your requirements.

Note that this document is intended to provide comprehensive description of all configuration options that can be consulted to understand the meaning of a particular option, its format and possible values. It will be quite hard to understand how to configure ejabberd by reading this document only - for this purpose the reader is recommended to read online Configuration Guide available at https://docs.ejabberd.im/admin/configuration.

👑 TOP LEVEL OPTIONS 👑

This section describes top level options of ejabberd 26.09. The options that changed in this version are marked with 🟠.

access_rules: {AccessName: {allow|deny: ACLName|ACLDefinition}} — This option defines basic.md#access-rules|Access Rules. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from access options of ejabberd modules). Each rule definition may contain arbitrary number of allow or deny sections, and each section may contain any number of ACL rules (see acl option). There are no access rules defined by default.

Example:

access_rules:
  configure:
    allow: admin
  something:
    deny: someone
    allow: all
  s2s_banned:
    deny: problematic_hosts
    deny: banned_forever
    deny:
      ip: 222.111.222.111/32
    deny:
      ip: 111.222.111.222/32
    allow: all
  xmlrpc_access:
    allow:
      user: peter@example.com
    allow:
      user: ivone@example.com
    allow:
      user: bot@example.com
      ip: 10.0.0.0/24

acl: {ACLName: {ACLType: ACLValue}} — This option defines ../configuration/basic.md#acl|access control lists: named sets of rules which are used to match against different targets (such as a JID or an IP address). Every set of rules has name ACLName: it can be any string except all or none (those are predefined names for the rules that match all or nothing respectively). The name ACLName can be referenced from other parts of the configuration file, for example in access_rules option. The rules of ACLName are represented by mapping {ACLType: ACLValue}. These can be one of the following:
- ip: Network — The rule matches any IP address from the Network.
- node_glob: Pattern — Same as node_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell.
- node_regexp: user_regexp@server_regexp — The rule matches any JID with node part matching regular expression user_regexp and server part matching regular expression server_regexp.
- resource: Resource — The rule matches any JID with a resource Resource.
- resource_glob: Pattern — Same as resource_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell.
- resource_regexp: Regexp — The rule matches any JID with a resource that matches regular expression Regexp.
- server: Server — The rule matches any JID from server Server. The value of Server must be a valid hostname or an IP address.
- server_glob: Pattern — Same as server_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell.
- server_regexp: Regexp — The rule matches any JID from the server that matches regular expression Regexp.
- user: Username — If Username is in the form of "user@server", the rule matches a JID against this value. Otherwise, if Username is in the form of "user", the rule matches any JID that has Username in the node part as long as the server part of this JID is any virtual host served by ejabberd.
- user_glob: Pattern — Same as user_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell.
- user_regexp: Regexp — If Regexp is in the form of "regexp@server", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is equal to "server". If Regexp is in the form of "regexp", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is any virtual host served by ejabberd.
acme: Options — basic.md#acme|ACME configuration, to automatically obtain SSL certificates for the domains served by ejabberd, which means that certificate requests and renewals are performed to some CA server (aka "ACME server") in a fully automated mode. The Options are:
- auto: true | false — Whether to automatically request certificates for all configured domains (that yet have no a certificate) on server start or configuration reload. The default is true.
- ca_url: URL — The ACME directory URL used as an entry point for the ACME server. The default value is https://acme-v02.api.letsencrypt.org/directory - the directory URL of Let’s Encrypt authority.
- cert_type: rsa | ec — A type of a certificate key. Available values are ec and rsa for EC and RSA certificates respectively. It’s better to have RSA certificates for the purpose of backward compatibility with legacy clients and servers, thus the default is rsa.
- contact: [Contact, ...] — A list of contact addresses (typically emails) where an ACME server will send notifications when problems occur. The value of Contact must be in the form of "scheme:address" (e.g. "mailto:user@domain.tld"). The default is an empty list which means an ACME server will send no notices.

Example:

acme:
  ca_url: https://acme-v02.api.letsencrypt.org/directory
  contact:
    - mailto:admin@domain.tld
    - mailto:bot@domain.tld
  auto: true
  cert_type: rsa

allow_contrib_modules: true | false — Whether to allow installation of third-party modules or not. See ../../admin/guide/modules.md#ejabberd-modules|ejabberd-modules documentation section. The default value is true.
allow_multiple_connections: true | false — This option is only used when the anonymous mode is enabled. Setting it to true means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect. This option is only useful in very special occasions. The default value is false.
anonymous_protocol: login_anon | sasl_anon | both — Define what authentication.md#anonymous-login-and-sasl-anonymous|anonymous protocol will be used:
- 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 → ../../developer/ejabberd-api/permissions.md|API Permissions.
append_host_config: {Host: Options} — Add a few specific options to a certain ../configuration/basic.md#virtual-hosting|virtual host.
auth_cache_life_time: timeout() — Same as cache_life_time, but applied to authentication cache only. If not set, the value from cache_life_time will be used.
auth_cache_missed: true | false — Same as cache_missed, but applied to authentication cache only. If not set, the value from cache_missed will be used.
auth_cache_size: pos_integer() | infinity — Same as cache_size, but applied to authentication cache only. If not set, the value from cache_size will be used.
auth_external_user_exists_check: true | false | force 🟠 — bestie, this one's a supplement to the user-existence check based on mod_last data. It's for auth methods that literally have no reliable way to tell if a user exists (looking at you, jwt and certificate-based auth 👀). It helps with processing offline messages for those users. Set it to force and that processing happens even when no external storage method is enabled — like when you're using certificate auth together with locally stored passwords.

🎀 Note about this option: added in 23.10, force added in 26.09.

The default value is true.

auth_method: [mnesia | sql | anonymous | external | jwt | ldap | pam, ...] — a whole list of authentication.md|authentication methods to use. And here's the vibe: if you define several methods, auth counts as successful as long as at least one of them succeeds ✨ The default value is [mnesia].
auth_opts: [Option, ...] — this one is used by the contributed module ejabberd_auth_http, which you can install from the ../../admin/guide/modules.md#ejabberd-contrib|ejabberd-contrib Git repository. Go read that module's README file for the deets, iykyk 🫶
auth_password_format: plain | scram — the option that decides in what format the users' passwords get stored: plain text, or authentication.md#scram|SCRAM format.

🌸 Note about this option: improved in 20.01.

plain: the password is stored as plain text in the database. Lowkey risky, ngl — because the passwords can absolutely be read if your database gets compromised 😭 This is the default value. This format lets clients authenticate using: the old Jabber Non-SASL (XEP-0078), SASL PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1/256/512(-PLUS).
scram: the password is not stored, only some information required to verify the hash the client provides. It is impossible to obtain the original plain password from the stored info — which is why, once this value is configured, it cannot be changed back to plain anymore, periodt. This format lets clients authenticate using: SASL PLAIN and SASL SCRAM-SHA-1/256/512(-PLUS). The SCRAM variant depends on the auth_scram_hash option.

The default value is plain.

auth_password_types_hidden_in_sasl1: [plain | scram_sha1 | scram_sha256 | scram_sha512] — a list of password types that should not be offered in SASL1 authentication.

💅 Note about this option: added in 25.07.

Here's the tea: SASL1, unlike SASL2, can't have a list of available mechanisms tailored to individual users. So it's possible the offered mechanisms won't be compatible with the stored password — especially if a new password type was added recently. This option lets you stop offering some mechanisms in SASL1, until that new password type is available for all users. Very thoughtful, honestly 👑

auth_scram_hash: sha | sha256 | sha512 — the hash algorithm that should be used to store passwords in authentication.md#scram|SCRAM format. ⚠️ Do not change this if you already have passwords generated with a different algorithm — users who have such passwords will not be able to authenticate. The default value is sha.
auth_stored_password_types: [plain | scram_sha1 | scram_sha256 | scram_sha512] — a list of password types that should be stored simultaneously for each user in the database.

🦋 Note about this option: added in 25.03.

So when the user sets the account password, the database gets updated to store the password in formats compatible with each type listed here. This is the move for migrating user passwords to a more secure format 🔥 Heads up: if this option is set, it will override the values set in the auth_scram_hash and auth_password_format options. The default value is [].

auth_use_cache: true | false — same as use_cache, but applied to the authentication cache only. If it's not set, the value from use_cache gets used instead 🫶
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 the subjectAltName field. There is no default value.

You can use host_config to specify this option per-vhost.

To set a specific file per listener, use the listener's listen-options.md#cafile|cafile option. Please notice that c2s_cafile overrides the listener's cafile option 👀

c2s_ciphers: [Cipher, ...] — a list of OpenSSL ciphers to use for c2s connections. The default value is shown in the example below:

Example:

c2s_ciphers:
  - HIGH
  - "!aNULL"
  - "!eNULL"
  - "!3DES"
  - "@STRENGTH"

c2s_dhfile: Path — full path to a file containing custom DH parameters to use for c2s connections. You could create such a file with the command openssl dhparam -out dh.pem 2048 ✨ If this option is not specified, then a 2048-bit MODP Group with 256-bit Prime Order Subgroup gets used, as defined in RFC5114 Section 2.3.
c2s_protocol_options: [Option, ...] — a 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 the system-defined file if possible.

For server connections, this ca_file option is overridden by the s2s_cafile option 💅

cache_life_time: timeout() — the amount of time a cached item is kept in the cache. Once it's expired, the corresponding item gets erased from the 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's an attempt to look up a value in a database and the value is not found, and this option is true, that attempt gets cached, and no attempts are 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 the cache. The rule of thumb: for all tables except rosters, set it to the number of maximum online users you expect. For roster, multiply that number by 20 or so 🧮 And watch out — if the cache size reaches this threshold, it's fully cleared, i.e. all items are deleted, and the corresponding warning gets logged. You should avoid frequent cache clearance, because it degrades performance 😭 The default value is 1000. Several modules have a similar option, and some core ejabberd parts support similar options too — see auth_cache_size, oauth_cache_size, router_cache_size, and sm_cache_size.
captcha_cmd: Path | ModuleName — full path to a script that generates basic.md#captcha|CAPTCHA images. The keyword @VERSION@ gets replaced with the ejabberd version number in XX.YY format. The keyword @SEMVER@ gets replaced with the 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 🙈

💜 Note about this option: improved in 23.01.

Examples:

When using the ejabberd installers or container image, the example captcha scripts can be used like this:

captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh

captcha_host: String — Deprecated. Use captcha_url instead. 👋
captcha_limit: pos_integer() | infinity — maximum number of basic.md#captcha|CAPTCHA generated images per minute for any given JID. This option is here to protect the server from CAPTCHA DoS attacks 🛡️ The default value is infinity.
captcha_pow: pos_integer() | false — offer an XEP-0158 SHA-256 hashcash (proof-of-work) challenge in the basic.md#captcha|CAPTCHA form, alongside the image challenge or on its own. The value is the difficulty: the number of hexadecimal digits of the SHA-256 digest a client must match. And unlike the image challenge, this one does not require captcha_cmd ✨ The default value is false.
captcha_url: URL | auto | undefined — an URL where basic.md#captcha|CAPTCHA requests should be sent.

🌈 Note about this option: improved in 23.04.

NOTE: you need to configure request_handlers for the ejabberd_http listener as well 💅 If set to auto, it builds the URL using a request_handler that's already enabled, with encryption if available. If set to undefined, it builds the URL using the deprecated captcha_host + /captcha. The default value is auto.

certfiles: [Path, ...] — this 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 use in TLS connections 🔐 Use this option when TLS is enabled in either of the 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. Don't skip this, bestie.

Examples:

If you use Let's Encrypt certificates for your domain domain.tld, the configuration will look like this:

certfiles:
  - /etc/letsencrypt/live/domain.tld/fullchain.pem
  - /etc/letsencrypt/live/domain.tld/privkey.pem

cluster_backend: Backend — a database backend to use for storing information about the cluster. The only available value so far is mnesia 👑
cluster_nodes: [Node, ...] — a list of Erlang nodes to hook up to on ejabberd startup 🫶. Ngl this one's mostly for ejabberd customization and sophisticated setups, so if that's not you, no stress. Default is an empty list.
default_db: mnesia | sql — your default database for storing persistent data in ejabberd (database.md#default-database). Some components get their own toplevel options like oauth_db_type, and lots of modules get their own module options, usually called db_type. Default value is mnesia.
default_ram_db: mnesia | redis | sql — the default volatile (in-memory) storage for ejabberd ✨. Same deal: some components have specific toplevel options like router_db_type and sm_db_type, and some modules have specific module options, usually named ram_db_type. Default is mnesia.
define_keyword: {NAME: Value} — 💅 note about this option: added in 25.03. Lets you define configuration keywords (../configuration/file-format.md#macros-and-keywords).

Example:

define_keyword:
  SQL_USERNAME: "eja.global"

host_config:
  localhost:
    define_keyword:
      SQL_USERNAME: "eja.localhost"

sql_username: "prefix.@SQL_USERNAME@"

define_macro: {NAME: Value} — 🎀 note about this option: improved in 25.03. Lets you define configuration macros (../configuration/file-format.md#macros-and-keywords).

Example:

define_macro:
  DEBUG: debug
  LOG_LEVEL: DEBUG
  USERBOB:
    user: bob@localhost

loglevel: LOG_LEVEL

acl:
  admin: USERBOB

disable_sasl_mechanisms: [Mechanism, ...] — bestie, this is where you list SASL mechanisms (like DIGEST-MD5 or SCRAM-SHA1) that should not be offered to the client 🙅‍♀️. For convenience, the value of Mechanism is case-insensitive. Default is an empty list, meaning nothing is disabled by default.
disable_sasl_scram_downgrade_protection: true | false — lets you turn off sending the data required by XEP-0474: SASL SCRAM Downgrade Protection. Real talk: there are known buggy clients out there (looking at you, the ones using strophejs 1.6.2) that literally can't authenticate when the server sends data from that spec 😭. So this option lets the server disable it and let even the buggy clients connect — but in exchange you get decreased MITM protection. Default value is false, which means the extension stays enabled 💖.
domain_balancing: {Domain: Options} — an algorithm to load-balance the components plugged into an ejabberd cluster (../guide/clustering.md#service-load-balancing). Basically you can plug one or several instances of the same component on each ejabberd node and the traffic gets distributed automatically ✨. This option specifies the algorithm for delivering messages to the component(s). For any component connected as Domain, the available Options are:
- component_number: 2..1000 — the number of components to balance.
- type: Value — how to deliver stanzas to connected components. Default value is random. Possible values:
  - bare_destination — by the bare JID (without resource) of the packet's to attribute
  - bare_source — by the bare JID (without resource) of the packet's from attribute is used
  - destination — an instance is chosen by the full JID of the packet's to attribute
  - random — an instance is chosen at random
  - source — by the full JID of the packet's from attribute

Example:

domain_balancing:
  component.domain.tld:
    type: destination
    component_number: 5
  transport.example.org:
    type: bare_source

ext_api_headers: Headers — a string of headers (separated with commas ,) that ejabberd will provide when sending ReST requests. Default value is an empty string of headers: "".
ext_api_http_pool_size: pos_integer() — sets the size of the HTTP pool, aka the max number of sessions the ejabberd ReST service handles at the same time. Default value is 100 🔥.
ext_api_path_oauth: Path — sets the base URI path when doing OAUTH ReST requests. Default value is "/oauth".
ext_api_url: URL — sets the base URI when making ReST requests. Default value is "http://localhost/api".
extauth_pool_name: Name — defines the pool name appendix in external auth (authentication.md#external-script), so the full pool name ends up being extauth_pool_Name. Default value is the hostname 🦋.
extauth_pool_size: Size — how many instances of the same external auth program (authentication.md#external-script) to start for better load balancing. Default is the number of available CPU cores 👑
extauth_program: Path — put the full path to the external authentication script (authentication.md#external-script) here. The script must be executable by ejabberd.
fqdn: Domain — a fully qualified domain name used in SASL DIGEST-MD5 authentication. Default is detected automatically ✨.
hide_sensitive_log_data: true | false — a privacy option so you don't log sensitive data (mostly IP addresses) 🙈. Default value is false for backward compatibility.
host_config: {Host: Options} — this one redefines Options for a virtual host Host (../configuration/basic.md#virtual-hosting). In the example below, LDAP auth is used on virtual host domain.tld and SQL is used on example.org.

Example:

hosts:
  - domain.tld
  - example.org

auth_method:
  - sql

host_config:
  domain.tld:
    auth_method:
      - ldap

hosts: [Domain1, Domain2, ...] — list of one or more host names (or domains) that ejabberd will serve (../configuration/basic.md#host-names). Heads up: this one is mandatory 💀.
hosts_alias: {Alias: Host} — 🌸 note about this option: added in 25.07. Defines aliases for existing vhosts managed by ejabberd. An alias may be a regexp expression. This option is only consulted by the ejabberd_http listener.

Example:

hosts:
  - domain.tld
  - example.org

hosts_alias:
  xmpp.domain.tld: domain.tld
  jabber.domain.tld: domain.tld
  mytest.net: example.org
  "exa*": example.org

include_config_file: [Filename, ...] | {Filename: Options} — read and include an additional file from Filename (../configuration/file-format.md#include-additional-files). If you provide it in the {Filename: Options} format, Options must be one of these:
- allow_only: [OptionName, ...] — only allows those options to be used in the included file Filename. Options that don't match this criteria are not accepted. Default value is to include all options.
- disallow: [OptionName, ...] — disallows those options in the included file Filename. Options that match this criteria are not accepted. Default value is an empty list.
install_contrib_modules: [Module, ...] — 💖 note about this option: added in 23.10. Modules from ../../admin/guide/modules.md#ejabberd-modules to install automatically at start time. Default value is an empty list of modules: [].

Example:

install_contrib_modules:
  - mod_tombstones

modules:
  mod_tombstones: {}

jwt_auth_only_rule: AccessName — this ACL rule defines the accounts that can use only the JWT auth method (authentication.md#jwt-authentication), even if other methods are also defined in the ejabberd config file. Like, if several auth methods are enabled for this host (JWT, SQL, …), users matching this rule can only use JWT. Default value is none.
jwt_jid_field: FieldName — by default the JID lives in the "jid" JWT field. This option lets you specify a different JWT field name where the JID is defined (authentication.md#jwt-authentication).
jwt_key: FilePath — path to the file containing the JWT key (authentication.md#jwt-authentication) 🔑

Supported file formats:

PEM format — standard PEM-encoded keys (RSA, EC, EdDSA, etc.)
JWK (JSON Web Key) — JSON format
JWK Set — JSON with a "keys" array (but it must contain exactly one key)

By default there is no path defined, that is: undefined.

language: Language — defines the default language of server strings that XMPP clients can see (../configuration/basic.md#default-language). If an XMPP client doesn't have an xml:lang attribute, this language is used. Default value is "en" 🌈.
ldap_backups: [Host, ...] — a list of IP addresses or DNS names of LDAP backup servers (see ../configuration/ldap.md#ldap-connection). When none of the servers listed in ldap_servers are reachable, ejabberd connects to these backup ones. Default is an empty list, aka no backup servers specified. Please notice 👀 ejabberd only connects to the next server when the existing connection is lost; it doesn't detect when a previously-attempted server becomes available again.
ldap_base: Base — the LDAP base directory that stores user accounts. There is no default value: you have to set this option for LDAP connections to work properly 😤.
ldap_deref_aliases: never | always | finding | searching — whether to dereference aliases or not. Default value is never.
ldap_dn_filter ({Filter: FilterAttrs}) — okay so this one's a lil extra filter that runs on whatever the main filter spits back at you 🫶. It does a whole extra LDAP lookup to build the complete result — which is exactly what you want when you literally cannot cram all your filter rules into ldap_filter. You can drop "%u", "%d", "%s" and "%D" pattern variables inside Filter: "%u" gets swapped for the user's part of the JID, "%d" gets swapped for the corresponding domain (virtual host), all the "%s" variables get replaced one after another by values from the attributes in FilterAttrs, and "%D" gets replaced by the Distinguished Name from the result set. There's no default value, which means the result just isn't filtered. > WARNING: because this filter does extra LDAP lookups, use it only as the last resort — try to define all filter rules in ldap_filter if you possibly can, bestie, fr fr. Example:

ldap_dn_filter:
  "(&(name=%s)(owner=%D)(user=%u@%d))": [sn]

ldap_encrypt (tls | none) — whether to encrypt the LDAP connection with TLS or not 💅. Default is none. NOTE: STARTTLS encryption is not supported — like, at all.
ldap_filter (Filter) — an LDAP filter as defined in RFC4515 ✨. No default value. Example: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))". NOTE: don't forget to close your brackets and don't use superfluous whitespaces (the filter is picky, she's got standards). Also you must not use the "uid" attribute in the filter, because that attribute gets appended to the filter automatically. iykyk.
ldap_password (Password) — the bind password 🔑. Default is an empty string.
ldap_port (1..65535) — port to connect to your LDAP server. Default port is 389 if encryption is disabled and 636 if encryption is enabled 🌸.
ldap_rootdn (RootDN) — bind Distinguished Name. Default is an empty string, which means "anonymous connection" 🙈.
ldap_servers ([Host, ...]) — a list of IP addresses or DNS names of your LDAP servers (see ../configuration/ldap.md#ldap-connection|LDAP connection). ejabberd connects immediately to all of them and reconnects infinitely if a connection is lost — she's committed 💖. 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 the PEM encoded certificate along with the PEM encoded private key. This certificate will be provided by ejabberd when TLS is enabled for LDAP connections 🎀. There's no default value, which means no client certificate gets 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 have failed 💀. Peer certificate = 0, CA certificate = 1, higher level CA certificate = 2, etc. So the value 2 means a chain can at most contain peer cert, CA cert, next CA cert, and an additional CA cert. Default value is 1.
ldap_tls_verify (false | soft | hard) — this one decides whether to verify the LDAP server certificate or not when TLS is enabled 👑. With hard, ejabberd doesn't proceed if the certificate is invalid. With soft, ejabberd proceeds even if the check has failed (she's being nice). Default is false, which means no checks are performed at all.
ldap_uids ([Attr] | {Attr: AttrFormat}) — LDAP attributes which hold a list of attributes to use as alternatives for getting the JID, where Attr is an LDAP attribute which holds the user's part of the JID, and AttrFormat must contain one and only one pattern variable "%u" which will be replaced by the user's part of the JID 🦋. For example, "%u@example.org". If the value is in the form of [Attr] then AttrFormat is assumed to be "%u".
listen ([Options, ...]) — the option for listeners configuration 🔥. See the listen.md|Listen Modules section for details.
log_burst_limit_count (Number) — note about this option: added in 22.10 ✨. The number of messages to accept in the log_burst_limit_window_time period before starting to drop them. Default 500.
log_burst_limit_window_time (Number) — note about this option: added in 22.10 ✨. The time period to rate-limit log messages by. Defaults to 1 second.
log_modules_fully ([Module, ...]) — note about this option: added in 23.01 ✨. List of modules that will log everything independently from the general loglevel option.
log_rotate_count (Number) — the number of rotated log files to keep 🎀. Default value is 1, which means it 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 that triggers rotation 🌈. If set to infinity, log rotation is disabled. Default value is 10 Mb expressed in bytes: 10485760.
loglevel (none | emergency | alert | critical | error | warning | notice | info | debug) — verbosity of ejabberd ../configuration/basic.md#logging|logging 💅. Default value is info. NOTE: previous versions of ejabberd had log levels defined in numeric format (0..5). Those numeric values are still accepted for backward compatibility, but they are not recommended — we've moved on, bestie.
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 the queue size reaches the limit (because, for example, the receiver of stanzas is too slow 🐌), the FSM and the corresponding connection (if any) get terminated and an error message is logged. The reasonable value depends on your hardware configuration. Allowed values are positive integers. Default value is 10000.
modules ({Module: Options}) — set all the modules.md|modules configuration options 🧚.
negotiation_timeout (timeout()) — time to wait for an XMPP stream negotiation to complete ⏳. When the timeout hits, the corresponding XMPP stream is closed. Default value is 120 seconds.
net_ticktime (timeout()) — this option tunes the tick time parameter of net_kernel. It tells the Erlang VM how often nodes should check whether intra-node communication was interrupted 💀. > This option must have an identical value on all nodes, or it will lead to subtle bugs. Usually leaving the default value alone is best — tweak it only if you know what you're doing, no cap. Default value is 1 minute.
new_sql_schema (true | false) — note about this option: obsoleted in 25.10 🙈. This option was renamed to sql_schema_multihost in ejabberd 25.10. Please update your configuration to use the new option name — she's moved on and so should you.
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 the OAuth cache only ✨. If not set, the value from cache_life_time is used.
oauth_cache_missed (true | false) — same as cache_missed, but applied to the OAuth cache only ✨. If not set, the value from cache_missed is used.
oauth_cache_rest_failure_life_time (timeout()) — note about this option: added in 21.01 ✨. The time that a failure in OAuth ReST is cached. Default value is infinity.
oauth_cache_size (pos_integer() | infinity) — same as cache_size, but applied to the OAuth cache only ✨. If not set, the value from cache_size is used.
oauth_client_id_check (allow | db | deny) — define whether client authentication is always allowed, denied, or whether it will depend on if the client ID is present in the database 👑. Default value is db.
oauth_db_type (mnesia | sql) — database backend to use for OAuth authentication 🦋. Default value is picked from the default_db option, or if that'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. Default is 4294967 seconds (that's a lot of seconds, iconique).
oauth_use_cache (true | false) — same as use_cache, but applied to the OAuth cache only ✨. If not set, the value from use_cache is used.
oom_killer (true | false) — enable or disable the OOM (out-of-memory) killer 💀. When system memory raises above the limit defined in the oom_watermark option, ejabberd triggers the OOM killer to terminate the 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 🫶. Default value is true.
oom_queue (Size) — trigger the OOM killer when some of the running Erlang processes have a message queue above this Size 😭. Note that such processes won't be killed if the 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 the OOM killer should be activated, with some of the processes possibly getting killed (see the oom_killer option) 🔥. Later, when memory drops below this Percent, the OOM killer is deactivated. Default value is 80 percents.
outgoing_s2s_families ([ipv6 | ipv4, ...]) — note about this option: changed in 23.01 ✨. Specify which address families to try, and in what order. Default is [ipv6, ipv4], which means it first tries connecting with IPv6, and if that fails it tries using IPv4. > Heads up: this option is obsolete and irrelevant when using ejabberd 23.01 and Erlang/OTP 22, or newer versions of them 🫶.
outgoing_s2s_ipv4_address (Address) — note about this option: added in 20.12 ✨. Specify the IPv4 address that will be used when establishing an outgoing S2S IPv4 connection, for example "127.0.0.1". Default value is undefined.
outgoing_s2s_ipv6_address (Address) — note about this option: added in 20.12 ✨. Specify the IPv6 address that will be used when establishing an outgoing S2S IPv6 connection, for example "::FFFF:127.0.0.1". 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 🌈. Default value is 5269.
outgoing_s2s_timeout: timeout() — how long (in seconds) ejabberd waits when it's trying to open an outgoing S2S connection before giving up. Default is 10 seconds — a whole decade in group-chat time, but okay. ⏳
pam_service: Name — the PAM service name for PAM authentication. Check your OS's PAM docs if you need the deets. Default value is ejabberd, cute and on-brand. 🎀
pam_userinfotype: username | jid — decides what ejabberd hands over to the PAM service: just the plain username, or the user's full jid. Default is username. Lowkey simple, highkey important. 💅
pgsql_users_number_estimate: true | false — whether to use PostgreSQL's estimation when counting registered users. Default is false. No cap. 🐘
queue_dir: Directory — if queue_type is set to file, this is the Directory where file queues get stored. Default is to keep queues inside the Mnesia directory. 🗂️
queue_type: ram | file — the default type of queues in ejabberd. Modules may have their own value for this option. ram means queues live in memory. If you set file, you can also specify where they go with the queue_dir option. Default is ram. ✨
redis_connect_timeout: timeout() — how long to wait for the connection to the Redis server to be re-established. Default is 1 second. 🧚
redis_db: Number — the Redis database number. Default is 0. 🍓
redis_password: Password — the password for the Redis server. Default is an empty string, i.e. no password. 🔑
redis_pool_size: Number — how many simultaneous connections to the Redis server. Default value is 10. 👑
redis_port: 1..65535 — the port where the Redis server accepts connections. Default is 6379. 🌀
redis_queue_type: ram | file — the type of request queue for the Redis server. See the queue_type option description for the explanation. Default value is whatever queue_type is set to, or ram if that one isn't set. 🌸
redis_server: Host | IP Address | Unix Socket Path — a hostname, IP address, or unix domain socket file for the Redis server. Set up a unix domain socket path like: "unix:/path/to/socket". Default value is localhost. Note about this option: improved in 24.12. 🦋
registration_timeout: timeout() — this is a global option for mod_register. It limits how often registrations can happen from a given IP or username. So if a user tries to register a new account from the same IP address or JID during this window after their previous registration, they get an error with the corresponding explanation. Set it to infinity to disable the whole limitation. Default value is 600 seconds. 😭
replaced_connection_timeout: timeout() — Note about this option: added in 26.01. The maximum time a new session will wait for the termination of the session it's replacing. This lets the old session properly send its unavailable presences and helps with potential race conditions between old and new session presences. 🫶
resource_conflict: setresource | closeold | closenew — > ⚠️ NOTE: this option is deprecated and may be removed anytime in future versions. The possible values match exactly the three possibilities described in XMPP Core: section 7.7.2.2. Default value is closeold. If the client uses old Jabber Non-SASL authentication (XEP-0078), then this option is not respected, and the action performed is closeold. 💀
rest_proxy: Host — Note about this option: added in 25.07. Address of an HTTP Connect proxy used by modules issuing REST calls (like ejabberd_oauth_rest). 🌈
rest_proxy_password: string() — Note about this option: added in 25.07. Password used to authenticate to the HTTP Connect proxy used by modules issuing REST calls (like ejabberd_oauth_rest). 🔐
rest_proxy_port: 1..65535 — Note about this option: added in 25.07. Port of the HTTP Connect proxy used by modules issuing REST calls (like ejabberd_oauth_rest). 🔌
rest_proxy_username: string() — Note about this option: added in 25.07. Username used to authenticate to the HTTP Connect proxy used by modules issuing REST calls (like ejabberd_oauth_rest). 🫧
router_cache_life_time: timeout() — same as cache_life_time, but applied to the 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 the 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 the routing table cache only. If not set, the value from cache_size will be used. 📦
router_db_type: mnesia | redis | sql — the database backend to use for routing information. Default value is picked from the default_ram_db option, or if that's not set, mnesia will be used. 🗄️
router_use_cache: true | false — same as use_cache, but applied to the 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. Default value is 5 seconds. 🔒
s2s_access: Access — this Access Rule defines what remote servers s2s connections can be established with. Default value is all — no restrictions, so it's allowed to connect s2s to/from all remote servers. 🌍
s2s_cafile: Path — a path to a file with CA root certificates 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. You can make one with the command openssl dhparam -out dh.pem 2048. If this option is not specified, a 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. Default value is 2. 🔁
s2s_dns_timeout: timeout() — the timeout for DNS resolving. Default value is 10 seconds. ⏱️
s2s_max_retry_delay: timeout() — the maximum allowed delay for an s2s connection retry after a failed connection attempt. Default value is 300 seconds (5 minutes). 😤
s2s_protocol_options: [Option, ...] — a 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 queue for s2s packets. See the queue_type option description for the explanation. Default value is whatever queue_type is set to, or ram if that one isn't set. 📬
s2s_timeout: timeout() — how long to wait before closing an idle s2s connection. Default value is 1 hour. 💤
s2s_tls_compression: true | false — whether to enable or disable TLS compression for s2s connections. Default value is false. 🗜️
s2s_use_starttls: true | false | optional | required — whether to use STARTTLS for s2s connections. false means STARTTLS is prohibited. true or optional means STARTTLS is enabled but plain connections are still allowed. required means only STARTTLS connections are allowed. Default value is false (for historical reasons). 🕰️
s2s_zlib: true | false — whether to use zlib compression (as defined in XEP-0138) or not. Default value is false. > ⚠️ WARNING: this type of compression is nowadays considered insecure. 💀
shaper: {ShaperName: Rate} — this option defines a set of shapers. Every shaper gets a name, ShaperName, that can be used elsewhere in the config file, like in the shaper_rules option. The shaper itself is defined by its Rate, where Rate is 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 back below the allowed maximum. In the example below, shaper normal limits traffic speed to 1,000 bytes/sec and shaper fast limits traffic speed to 50,000 bytes/sec: 🚦

Example:

shaper:
  normal: 1000
  fast: 50000

shaper_rules: {ShaperRuleName: {Number|ShaperName: ACLName|ACLDefinition}} — this option defines shaper rules to use for matching users/hosts. The semantics are similar to the access_rules option — the only difference is that instead of using allow or deny, you use the name of a shaper (defined in the shaper option) or a positive number. 💫

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 the 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 the 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 the client sessions table cache only. If not set, the value from cache_size will be used. 📊
sm_db_type: mnesia | redis | sql — the database backend to use for client sessions information. Default value is picked from the default_ram_db option, or if that's not set, mnesia will be used. 🗃️
sm_use_cache — true | false. Same vibe as use_cache, bestie, except it only applies to the client sessions table cache ✨. If you don't set it, the value from use_cache gets used instead.
sql_connect_timeout — timeout(). How long we're willing to wait for a connection to the SQL server to actually get established 🫶. Default is 5 seconds.
sql_database — DatabaseName | PathSqliteFile. The SQL database name, and the default value is ejabberd. 🩵 But if sql_type is set to sqlite, this has to be a full path to a database file, and the default value becomes: "@DATABASE_PATH@/sqlite/@HOST@.sqlite". (Note: improved in 26.04, slay.)
sql_flags — [mysql_alternative_upsert]. Note: added in 24.02 💫. This one takes a list of SQL flags, and it's empty by default. Setting mysql_alternative_upsert forces the alternative upsert implementation in MySQL. iykyk.
sql_keepalive_interval — timeout(). An interval where we fire off a dummy SQL request just to keep those database connections alive 💅. There is no default value, so no keepalive requests get made unless you ask for them.
sql_odbc_driver — Path. Note: added in 20.12 🦋. Path to the ODBC driver used to connect to a Microsoft SQL Server database. This only applies if the sql_type option is set to mssql and sql_server is not an ODBC connection string. Default value: libtdsodbc.so.
sql_password — Password. The password for SQL authentication. Default is empty string 🙈.
sql_pool_size — Size. Number of connections to the SQL server that ejabberd will open for each virtual host. 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 🔥. Defaults: 3306 for MySQL, 5432 for PostgreSQL, 1433 for MS SQL. The option has no effect for SQLite.
sql_prepared_statements — true | false. Note: added in 20.01. This is true by default, and it's useful for disabling prepared statements. Valid for PostgreSQL and MySQL 👍.
sql_query_timeout — timeout(). How long to wait for an SQL query response before we lose our patience 😭. Default value is 60 seconds.
sql_queue_type — ram | file. The type of request queue for the SQL server. Peep the description of the queue_type option for the explanation. The default value is whatever queue_type is set to, or ram if that one isn't set at all.
sql_schema_multihost — true | false. Note: renamed in 25.10 🌸. Whether to use the database.md#singlehost-or-multihost|multihost SQL schema. All schemas live at https://github.com/processone/ejabberd/tree/26.09/sql. There are two schemas available:
- The legacy singlehost schema stores one XMPP domain into one ejabberd database.
- The multihost schema can handle several XMPP domains in a single ejabberd database.

The multihost schema is preferable when you're serving several XMPP domains and/or changing domains from time to time — it avoids having to manage several databases and deal with complex configuration changes 👑. The default depends on the ../../admin/install/source.md#configure|./configure flag --enable-sql-schema-multihost, which is set at compile time.

sql_server — Host | IP Address | ODBC Connection String | Unix Socket Path. Note: improved in 24.06 🧚. The hostname or IP address of the SQL server. For sql_type mssql or odbc, this can also be an ODBC connection string. When sql_type is mysql or pgsql, this can be the path to a unix domain socket, expressed like: "unix:/path/to/socket". The default value is localhost.
sql_ssl — true | false. Note: improved in 20.03. Whether to use SSL encrypted connections to the SQL server 🔐. Only available for MySQL, MS SQL and PostgreSQL. Default value is false.
sql_ssl_cafile — Path. A path to a file with CA root certificates that'll be used to verify SQL connections. This implies the sql_ssl and sql_ssl_verify options are set to true. There is no default, which means certificate verification is disabled. This option has no effect for MS SQL.
sql_ssl_certfile — Path. A path to a certificate file that'll be used for SSL connections to the SQL server. Implies sql_ssl is set to true. There's no default, which means ejabberd won't provide a client certificate to the SQL server 🙈. This option has no effect for MS SQL.
sql_ssl_verify — true | false. Whether to verify the SSL connection to the SQL server against the CA root certificates defined in the sql_ssl_cafile option. Implies sql_ssl is set to true. No effect for MS SQL. Default value is false.
sql_start_interval — timeout(). How long to wait before retrying to restore a failed SQL connection 🫠. Default value is 30 seconds.
sql_type — mssql | mysql | odbc | pgsql | sqlite. The type of SQL connection. Default is odbc.
sql_username — Username. A user name for SQL authentication. Default value is ejabberd ✨.
trusted_proxies — all | [Network1, Network2, ...]. Tells us which proxies are trusted when an HTTP request contains the X-Forwarded-For header. You can specify all to allow every proxy, or give a list of IPs, possibly with masks. Default value is an empty list. With this option you can actually know the real IP of the request — for admin purposes, or for 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. Otherwise the client can set it themselves, and as a result the IP value cannot be trusted for security rules in ejabberd 💀.

update_sql_schema — true | false. Note: updated in 24.06. Lets ejabberd update the SQL schema in MySQL, PostgreSQL and SQLite databases 🛠️. This option was added in ejabberd 23.10, and enabled by default since 24.06. Default value is true.
update_sql_schema_timeout — timeout(). Note: added in 24.07. Time allocated to SQL schema update queries. Default is set to 5 minutes ⏳.
use_cache — true | false. Turn the cache on or off. 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 use by client developers — do not enable it in a production environment 😱. Default value is false.

version — string(). This option sets a custom ejabberd version that different parts of ejabberd will use, for example the mod_version module. By default the value is obtained at compile time from the underlying version control system 🦋.
websocket_origin — ignore | URL. This option enables validation of the Origin header, to protect against connections from domains other than the one given in the config file 🔒. That way, the lower-layer load balancer can be picked for a specific ejabberd implementation while still providing a secure WebSocket connection. Default value is ignore. An example value of the URL is "https://test.example.org:8081".
websocket_ping_interval — timeout(). Defines the time between pings the server sends 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 is assumed closed. A value of 0 disables the feature. Heads up: this option makes the server send pings only for connections using the RFC compliant protocol — for older style connections, the server expects whitespace pings to be used for this purpose. Default value is 60 seconds.
websocket_timeout — timeout(). Amount of time without any communication after which the connection gets closed 💤. Default value is 300 seconds.

🧩 MODULES 🧩

This section describes the modules options of ejabberd 26.09 ✨. The modules that changed in this version are marked with 🟠.

mod_adhoc

def:ad-hoc command: a Command that can be executed by an XMPP client using XEP-0050 🌈.

This module implements XEP-0050: Ad-Hoc Commands. It's an auxiliary module, so it's only needed by some of the other modules 💅.

Available options:

report_commands_node — true | false. Provide the Commands item in the Service Discovery. Default value: false.

mod_adhoc_api

Note: added in 25.03 🦋.

Execute (def:API commands) in an XMPP client using XEP-0050: Ad-Hoc Commands. This module requires mod_adhoc (to execute the commands), and recommends mod_disco (to discover the commands) 🫶.

Available options:

default_version — integer() | string(). What API version to use. If you set an ejabberd version, it'll use the latest API version that was available in that (def:c2s) ejabberd version — for example, setting "24.06" in this option implies 2 👑. The default value is the latest version.

Example:

acl:
  admin:
    user: jan@localhost

api_permissions:
  "adhoc commands":
    from: mod_adhoc_api
    who: admin
    what:
      - "[tag:roster]"
      - "[tag:session]"
      - stats
      - status

modules:
  mod_adhoc_api:
    default_version: 2

mod_admin_extra

This module provides additional administrative commands 🔥.

Details for some commands:

ban_account API: this command kicks all the connected sessions of the account from the server 💀. It also changes their password to a randomly generated one, so they can't log in anymore unless a server administrator changes their password again. You can define the reason of the ban. The new password also includes the reason and the date and time of the ban. See an example below ⬇️.

push_roster API (and push_roster_all API): the roster file must be placed — if you're on Windows — on the directory where you installed ejabberd: C:/Program Files/ejabberd or similar 🪟. If you use another Operating System, place the file on the same directory where the .beam files are installed. See below an example roster file 🍓.

srg_create API: oh and if you wanna put a group Name with blank spaces inside it, you wrap it with "' and '" to mark where the Name starts and where it ends 💅 (yes it's giving dramatic but it works). Example below, bestie.

This module has no options. Like, zero. Not a single one. Iconic of it honestly 🎀

Examples

With this config, 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 the roster file for the push_roster API:

[{<<"bob">>, <<"example.org">>, <<"workers">>, <<"Bob">>},
{<<"mart">>, <<"example.org">>, <<"workers">>, <<"Mart">>},
{<<"Rich">>, <<"example.org">>, <<"bosses">>, <<"Rich">>}].

With this next call, the sessions of the local account whose JID is boby@example.org get kicked, and its password gets set to something like BANNED_ACCOUNT—20080425T21:45:07—2176635—Spammed_rooms 😭

ejabberdctl vhost example.org ban_account boby "Spammed rooms"

Call to the srg_create API using double-quotes and single-quotes:

ejabberdctl srg_create g1 example.org "'Group number 1'" this_is_g1 g1

API Tags — here's the whole lil tag family 🫶:

../../developer/ejabberd-api/admin-tags.md#accounts|accounts
../../developer/ejabberd-api/admin-tags.md#erlang|erlang
../../developer/ejabberd-api/admin-tags.md#last|last
../../developer/ejabberd-api/admin-tags.md#private|private
../../developer/ejabberd-api/admin-tags.md#purge|purge
../../developer/ejabberd-api/admin-tags.md#roster|roster
../../developer/ejabberd-api/admin-tags.md#session|session
../../developer/ejabberd-api/admin-tags.md#shared_roster_group|shared_roster_group
../../developer/ejabberd-api/admin-tags.md#stanza|stanza
../../developer/ejabberd-api/admin-tags.md#statistics|statistics
../../developer/ejabberd-api/admin-tags.md#vcard|vcard

mod_admin_update_sql

This module is literally the glow-up artist for your existing SQL database — it converts it from the singlehost schema to the multihost schema ✨. Check the section database.md#singlehost-or-multihost|Singlehost or Multihost for the deets.

Heads up bestie: only MS SQL, MySQL, and PostgreSQL are supported. That's the whole guest list 🙈

When the module is loaded, use the update_sql API.

This module has no options — again, nothing to configure. We love a low-maintenance queen 👑

mod_announce

This module lets configured users broadcast announcements and set the message of the day (MOTD) 📢. Configured users can do all this with an XMPP client either by using Ad-Hoc Commands or by sending messages to specific JIDs. Equivalent API commands are available too, so pick your vibe 🎀

Note This module can be resource intensive on large deployments, because it may broadcast a whole lot of messages. Like, a LOT. It should be disabled for instances of ejabberd with hundreds of thousands of users 💀 no cap.

To send announcements using XEP-0050: Ad-Hoc Commands, this module requires mod_adhoc (to actually execute the commands), and it recommends mod_disco (so people can discover the commands). Teamwork, bestie 🤝

To send announcements by sending messages to specific JIDs, these are the destination JIDs:

example.org/announce/all: sends the message to all registered users in that vhost. If the user is online and connected to several resources, only the resource with the highest priority receives the message. If the registered user isn't connected, the message is stored offline, assuming offline storage (see mod_offline) is enabled 📥
example.org/announce/online: sends the message to all connected users. If the user is online and connected to several resources, all resources receive the message 🦋
example.org/announce/motd: sets the message of the day (MOTD) that's sent to users when they log in. It also sends the message to all connected users (similar to announce/online) ⭐
example.org/announce/motd/update: sets the message of the day (MOTD) that's sent to users when they log in. This one does not send the message to any currently connected user 🌸
example.org/announce/motd/delete: removes the existing message of the day (MOTD) by sending a message to this JID 🧹

And there are similar destination JIDs that apply to all virtual hosts in ejabberd:

example.org/announce/all-hosts/all: send to all registered accounts
example.org/announce/all-hosts/online: send to online sessions
example.org/announce/all-hosts/motd: set MOTD and send to online
example.org/announce/all-hosts/motd/update: update MOTD
example.org/announce/all-hosts/motd/delete: delete MOTD

Available options

access: AccessName — this one decides who's allowed to send announcements and set the message of the day. The default value is none, which means nobody is able to send such messages 🙅‍♀️
cache_life_time: timeout() — same as the top-level cache_life_time option, but applied to this module only 💫
cache_missed: true | false — same as the top-level cache_missed option, but applied to this module only 💫
cache_size: pos_integer() | infinity — same as the top-level cache_size option, but applied to this module only 💫
db_type: mnesia | sql — same as the top-level default_db option, but applied to this module only 💫
use_cache: true | false — same as the top-level use_cache option, but applied to this module only 💫

API Tags:

../../developer/ejabberd-api/admin-tags.md#announce|announce

mod_antispam

Note about this option: added in 25.07 ✨

This module filters spam messages and subscription requests coming in from remote servers, based on Real-Time Block Lists (RTBL), lists of known spammer JIDs, and/or URLs mentioned inside spam messages 🚫. Anything classified as spam gets rejected with an error (and an [info] message gets logged), unless the sender is subscribed to the recipient's presence. Rude spammers, be gone 💅

Available options

access_spam: Access — access rule that controls which accounts may receive spam messages. If the rule returns allow for a given recipient, spam messages aren't rejected for that recipient. The default value is none, which means all recipients are subject to spam filtering verification 🔍
cache_size: pos_integer() — the maximum number of JIDs that get cached for sending spam URLs. If that limit is exceeded, the least recently used entries get removed from the cache. Setting this option to 0 disables the caching feature entirely. Note that separate caches are used for each virtual host, and that the caches aren't distributed across cluster nodes 🫠. The default value is 10000
rtbl_services: [Service] — queries an RTBL service to get domains to block, as provided by xmppbl.org. Ngl, right now this option only supports one service in that list. For blocking spam and abuse on MUC channels, please use mod_muc_rtbl for now 🙏. If only the host is provided, the default node names are assumed. If the node name is different than spam_source_domains, you can set up the custom node name with the option spam_source_domains_node. The default value is an empty list of services.

Example:

rtbl_services:
  - pubsub.server1.localhost:
      spam_source_domains_node: actual_custom_pubsub_node

spam_domains_file: none | Path — path to a plain text file holding a list of known spam domains, one domain per line. Messages and subscription requests sent from one of the listed domains get classified as spam if the sender isn't in the recipient's roster. This list of domains gets merged with the one retrieved by an RTBL host, if any is given. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is none 🗂️
spam_dump_file: false | true | Path — path to the file where blocked messages get stored. Use an absolute path, or the @LOG_PATH@ predefined keyword to store logs in the same place as the other ejabberd log files. If set to false, it doesn't dump stanzas, which is the default. If set to true, it stores them in "@LOG_PATH@/spam_dump_@HOST@.log" 📝
spam_jids_file: none | Path — path to a plain text file holding a list of known spammer JIDs, one JID per line. Messages and subscription requests sent from one of the listed JIDs get classified as spam. Messages containing at least one of the listed JIDs are classified as spam as well. On top of that, the sender's JID gets cached, so future traffic originating from that JID will also be classified as spam 👀. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is none
spam_urls_file: none | Path — path to a plain text file holding a list of URLs known to be mentioned in spam message bodies. Messages containing at least one of the listed URLs get classified as spam. And again, the sender's JID gets cached, so future traffic originating from that JID will also be classified as spam 💀. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is none
whitelist_domains_file: none | Path — path to a file holding a list of domains to whitelist from being blocked, one per line. If a domain is in spam_domains_file or, more realistically, in a domain sent by an RTBL host (see option rtbl_services), then this domain gets ignored and stanzas from there won't be blocked 🕊️. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is none

Example

modules:
  mod_antispam:
    rtbl_services:
      - xmppbl.org
    spam_jids_file: "@CONFIG_PATH@/spam_jids.txt"
    spam_dump_file: "@LOG_PATH@/spam/host-@HOST@.log"

mod_auth_fast

Note about this option: improved in 26.07 🚀

This module adds support for XEP-0484: Fast Authentication Streamlining Tokens, which lets users authenticate using self-managed tokens 🔑. Self-managed? We love an independent era fr fr.

Available options:

db_type — mnesia | sql. Note about this option: improved in 26.07. It's literally the same thing as the top-level default_db option, bestie, except it only applies to this module. Local queen behaviour 💅
token_lifetime — timeout(). How long tokens get to stick around, counted from the moment they were created. Default is set to 30 days. Lowkey generous but slay 🎀
token_refresh_age — timeout(). This one's the age a token has to hit before it qualifies for an automatic glow-up (aka refresh). Default is set to 1 day ✨

Example 🍓

modules:
  mod_auth_fast:
    token_lifetime: 14days

🦋 mod_avatar

Okay so this module's whole thing is handling both the legacy and the modern XMPP clients that post avatars — which is a mess, but she copes. The whole process is described in XEP-0398: User Avatar to vCard-Based Avatars Conversion 📸

Bonus: the module also supports converting between avatar image formats on the fly. Obsessed 😭

Heads up: the module depends on mod_vcard, mod_vcard_xupdate and mod_pubsub. No cap, it needs all three 🫶

Available options: 👑

convert — {From: To}. This defines your image conversion rules: whatever format is in From gets converted into the format in To. The value of From can also be default, which is the match-all rule. NOTE: the list of supported formats is detected at compile time, depending on which image libraries are actually installed on your system. So like, don't come for her if your fave format isn't there 🙈

Here's the vibe:

convert:
  webp: jpg
  default: png

rate_limit — Number. Caps any given JID to that number of avatars it can convert per minute. Why? To protect the server from image conversion DoS, obviously 💀 The default value is 10.

🚫 mod_block_strangers

This one blocks and logs any messages coming from an unknown entity. So if the writing entity isn't in your roster, you can let this module drop and/or log the message. By default you'll just not receive messages from that entity — silent treatment, iconic. Enable this module if you want to drop SPAM messages 📵

Available options: 🌸

access — AccessName. Use this when allow_local_users and allow_transports just aren't enough. It's an Access Rule where deny means the stanza will be rejected — with one exception if option captcha is configured. And allow means the sender is whitelisted and the stanza passes right through, VIP style 🎟️ The default value is none, which means nothing is whitelisted.
allow_local_users — true | false. Specifies if strangers from the same local host should be accepted or not. Default value is true.
allow_transports — true | false. If it's true and some server's JID is in the user's roster, then messages from any user of that server are accepted, even if there's no subscription present. Default value is true.
captcha — true | false. Whether to generate CAPTCHA challenges in response to incoming presence subscription requests from strangers. See also section basic.md#captcha|CAPTCHA of the Configuration Guide 🧩 The default value is false.
drop — true | false. Specifies if strangers' messages should be dropped or not. Default value is true.
log — true | false. Specifies if strangers' messages should be logged (as an info message) in ejabberd.log. Default value is false.

🔒 mod_blocking

Implements XEP-0191: Blocking Command. That's it, that's the tweet 💅

This module depends on mod_privacy, where all the actual configuration is performed.

The module has no options. She's low maintenance, we love her 🌈

🌐 mod_bosh

This module implements XMPP over BOSH as defined in XEP-0124 and XEP-0206. BOSH stands for Bidirectional-streams Over Synchronous HTTP — yes, the acronym ate 🔥 It makes it possible to simulate the long-lived connections that XMPP requires, but over the HTTP protocol. In practice? This module lets you use XMPP in a browser without WebSocket support, and more generally gives you a way to use XMPP while having to get through an HTTP proxy 🚇

Available options: ✨

cache_life_time — timeout(). Same as the top-level cache_life_time option, but applied to this module only.
cache_missed — true | false. Same as the top-level cache_missed option, but applied to this module only.
cache_size — pos_integer() | infinity. Same as the top-level cache_size option, but applied to this module only.
json — true | false. This option has no effect. Yeah. She's just there for the vibes 💀
max_concat — pos_integer() | infinity. Limits the number of stanzas the server will send in a single bosh request. Default value is unlimited.
max_inactivity — timeout(). Defines the maximum inactivity period. Default value is 30 seconds.
max_pause — pos_integer(). The maximum length of a temporary session pause (in seconds) that a client can request. 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 🕵️ Default value is false.
queue_type — ram | file. Same as the top-level queue_type option, but applied to this module only.
ram_db_type — mnesia | sql | redis. Same as the top-level default_ram_db option, but applied to this module only.
use_cache — true | false. Same as the top-level use_cache option, but applied to this module only.

Example 🎀

listen:
  -
    port: 5222
    module: ejabberd_c2s
  -
    port: 5443
    module: ejabberd_http
    request_handlers:
      /bosh: mod_bosh

modules:
  mod_bosh: {}

🧩 mod_caps

Implements XEP-0115: Entity Capabilities. The main character purpose here is providing PEP functionality — see mod_pubsub 👑

Available options: 💜

cache_life_time — timeout(). Same as the top-level cache_life_time option, but applied to this module only.
cache_missed — true | false. Same as the top-level cache_missed option, but applied to this module only.
cache_size — pos_integer() | infinity. Same as the top-level cache_size option, but applied to this module only.
db_type — mnesia | sql. Same as the top-level default_db option, but applied to this module only.
use_cache — true | false. Same as the top-level use_cache option, but applied to this module only.

📬 mod_carboncopy

Implements XEP-0280: Message Carbons — the module broadcasts messages on all connected user resources (aka devices). So everything's synced everywhere, no more "wait which laptop was I on" energy 🫶

The module has no options.

💤 mod_client_state

Okay this one's actually so smart. It lets you queue certain types of stanzas when a client indicates that the user isn't actively using the client right now — see XEP-0352: Client State Indication. Which saves bandwidth and resources. Mother 🌍

A stanza gets 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). And the queue gets 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. Flush = she's back, give her everything 🚿

Available options: 🌙

queue_chat_states — true | false. Queues "standalone" chat state notifications (as defined in XEP-0085: Chat State Notifications) while a client indicates inactivity. Default value is true.
queue_pep — true | false. Queues PEP notifications while a client is inactive. When the queue gets flushed, only the most recent notification of a given PEP node is delivered — no spam, just the latest tea ☕ Default value is true.
queue_presence — true | false. While a client is inactive, queues presence stanzas that indicate (un)availability. Default value is true.

⚙️ mod_configure

Note about this option: improved in 25.10.

This module provides server configuration functionalities using XEP-0030: Service Discovery and XEP-0050: Ad-Hoc Commands:

List and discover outgoing s2s, online client sessions and all registered accounts
Most of the ad-hoc commands defined in XEP-0133: Service Administration
Additional custom ad-hoc commands specific to ejabberd

Ad-hoc commands from XEP-0133 that behave differently to the XEP 🙃

get-user-roster: returns standard fields instead of roster items that the client cannot display

Those ad-hoc commands from XEP-0133 do not include in the response the client that executed the command:

get-active-users-num
get-idle-users-num
get-active-users
get-idle-users

Those ad-hoc commands from XEP-0133 are not implemented at all, sorry bestie 😭

edit-blacklist
edit-whitelist
edit-admin

This module requires mod_adhoc (to execute the commands) and recommends mod_disco (to discover the commands).

Please notice that all the ad-hoc commands implemented by this module have an equivalent API Command that you can execute using mod_adhoc_api or any other API frontend. iykyk 💅

Available options: 👑

access — AccessName. Note about this option: added in 25.03. Defines which access rule is used to control who's allowed to access the features provided by this module. The default value is configure 🔐

Example 🍓

acl:
  admin:
    user: sun@localhost

access_rules:
  configure:
    allow: admin

modules:
  mod_configure:
    access: configure

💬 mod_conversejs

Note about this option: improved in 25.07.

This module serves a simple page for the Converse XMPP web browser client. She's cute, she's functional, we stan 🌸

To use this module, in addition to adding it to the modules section, you must also enable it in listen → ejabberd_http → listen-options.md#request_handlers|request_handlers. Both places, bestie, don't skip step two 🙈

Make sure either mod_bosh or listen.md#ejabberd_http_ws|ejabberd_http_ws are enabled in at least one request_handlers.

When conversejs_css and conversejs_script are auto, by default they point to the public Converse client. Free real estate ✨

When this module is enabled in modules, it adds automatically a request handler and link in WebAdmin. . 👑

This module is available since ejabberd 21.12.

Available options:

bosh_service_url — auto | BoshURL — okay so this is the BOSH service URL Converse can connect to. The keyword @HOST@ gets replaced with the real virtual host name, no cap. If it’s set to auto, it builds the URL of the first configured BOSH request handler. Default value is auto. ✨
conversejs_css — auto | URL — the Converse CSS URL, bestie. The keyword @HOST@ gets swapped for the hostname. Default value is auto. 🎀
conversejs_options — {Name: Value} — quick note: this option was added in 22.05. It lets you specify extra options passed to Converse. See Converse configuration. Only boolean, integer and string values are supported; lists are not supported. 💅
conversejs_plugins — [Filename] — a list of additional local files to include as scripts in the homepage. Please make sure those files are available in the path specified in conversejs_resources option, in subdirectory plugins/. Notice that libsignal is only required for OMEMO encryption in Converse 13 or lower; Converse 14 uses and includes libomemo. If using the public Converse client, then "libsignal" gets replaced with the URL of the public library. Default value is []. 🦋
conversejs_resources — Path — quick note: this option was added in 22.05. Local path to the Converse files. If not set, the public Converse client will be used instead. 🌸
conversejs_script — auto | URL — the Converse main script URL. The keyword @HOST@ gets replaced with the hostname. 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. Default value is @HOST@. 💖
websocket_url — auto | WebSocketURL — a WebSocket URL to which Converse can connect. The @HOST@ keyword is replaced with the real virtual host name. If set to auto, it builds the URL of the first configured WebSocket request handler. Default value is auto. 🔥

Examples: 🫶

Manually setup WebSocket url, and use the public Converse client:

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      /bosh: mod_bosh
      /websocket: ejabberd_http_ws
      /conversejs: mod_conversejs

modules:
  mod_bosh: {}
  mod_conversejs:
    websocket_url: "ws://@HOST@:5280/websocket"

Host Converse locally and let auto detection of WebSocket and Converse URLs:

listen:
  -
    port: 443
    module: ejabberd_http
    tls: true
    request_handlers:
      /websocket: ejabberd_http_ws
      /conversejs: mod_conversejs

modules:
  mod_conversejs:
    conversejs_resources: "/home/ejabberd/conversejs-x.y.z/package/dist"
    conversejs_plugins: ["libsignal-protocol.min.js"]
    # File path is: /home/ejabberd/conversejs-x.y.z/package/dist/plugins/libsignal-protocol.min.js

Configure some additional options for Converse:

modules:
  mod_conversejs:
    websocket_url: auto
    conversejs_options:
      auto_away: 30
      clear_cache_on_logout: true
      i18n: "pt"
      locked_domain: "@HOST@"
      message_archiving: always
      theme: dracula

🌸 mod_delegation 🌸

Okay so 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 a specific namespace. This may be applied for an external PEP service, iykyk. 💫

⚠️ Warning — Security issue: Namespace delegation gives components access to sensitive data, so permission should be granted carefully, only if you trust the component. Bestie, seriously, be careful with this one.

💡 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 — this option defines which components are allowed for namespace delegation. Default value is none.
- filtering — Attributes — the list of attributes. Currently not used.

Examples: ✨

Make sure you do not delegate the same namespace to several services at the same time. As in the example provided later, to have the sat-pubsub.example.org component perform correctly disable the mod_pubsub module.

access_rules:
  external_pubsub:
    allow: external_component
  external_mam:
    allow: external_component

acl:
  external_component:
    server: sat-pubsub.example.org

modules:
  mod_delegation:
    namespaces:
      urn:xmpp:mam:1:
        access: external_mam
      http://jabber.org/protocol/pubsub:
        access: external_pubsub

🦋 mod_disco 🦋

This module adds support for XEP-0030: Service Discovery. With this module enabled, services on your server can be discovered by XMPP clients. It’s giving discovery era, periodt. 🔍

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. 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. Default value is ejabberd. 👑
server_info — [Info, ...] — specify additional information about the server, as described in XEP-0157: Contact Addresses for XMPP Services. Every Info element in the list is constructed from the following options:
- modules — all | [Module, ...] — the value can be the keyword all, in which case the information is reported in all the services, or a list of ejabberd modules, in which case the information is only specified for the services provided by those modules.
- name — Name — the field var name that will be defined. See XEP-0157 for some standardized names.
- urls — [URI, ...] — a list of contact URIs, such as HTTP URLs, XMPP URIs and so on.

Example: 🎀

server_info:
  -
    modules: all
    name: abuse-addresses
    urls: ["mailto:abuse@shakespeare.lit"]
  -
    modules: [mod_muc]
    name: "Web chatroom logs"
    urls: ["http://www.example.org/muc-logs"]
  -
    modules: [mod_disco]
    name: feedback-addresses
    urls:
      - http://shakespeare.lit/feedback.php
      - mailto:feedback@shakespeare.lit
      - xmpp:feedback@shakespeare.lit
  -
    modules:
      - mod_disco
      - mod_vcard
    name: admin-addresses
    urls:
      - mailto:xmpp@shakespeare.lit
      - xmpp:admins@shakespeare.lit

💀 mod_fail2ban 💀

The module bans IPs that show the malicious signs. Currently only C2S authentication failures are detected. 🚨

Unlike the standalone program, mod_fail2ban clears the record of authentication failures after some time since the first failure or on a successful authentication. It also does not simply block network traffic, but provides the client with a descriptive error message. 💅

⚠️ Warning — You should not use this module behind a proxy or load balancer. ejabberd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer. You can lock all your user base out of ejabberd when using this module behind a proxy. No cap, that’s a whole mess.

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. Default value is none. ✨
c2s_auth_ban_lifetime — timeout() — the lifetime of the IP ban caused by too many C2S authentication failures. Default value is 1 hour. ⏳
c2s_max_auth_failures — Number — the number of C2S authentication failures to trigger the IP ban. Default value is 20. 🔥

API Tags: ../../developer/ejabberd-api/admin-tags.md#accounts|accounts

🧚 mod_host_meta 🧚

Note about this option: added in 22.05. 💖

This module serves small host-meta files as described in XEP-0156: Discovering Alternative XMPP Connection Methods. 🌈

To use this module, in addition to adding it to the modules section, you must also enable it in listen → ejabberd_http → listen-options.md#request_handlers|request_handlers. 👀

Notice it only works if listen.md#ejabberd_http|ejabberd_http has listen-options.md#tls|tls enabled. Important, bestie. 🔐

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. 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. Default value is auto. 🦋

Example: 💫

listen:
  -
    port: 443
    module: ejabberd_http
    tls: true
    request_handlers:
      /bosh: mod_bosh
      /websocket: ejabberd_http_ws
      /.well-known/host-meta: mod_host_meta
      /.well-known/host-meta.json: mod_host_meta

modules:
  mod_bosh: {}
  mod_host_meta:
    bosh_service_url: "https://@HOST@:5443/bosh"
    websocket_url: "wss://@HOST@:5443/websocket"

🌸 `mod_http_api`

Okay bestie, this one is so useful — it hands you a ReST interface so you can call [ejabberd API commands](../../developer/ejabberd-api/index.md) with JSON data. Like, actual API calls. Obsessed. ✨

Heads up though: adding it to modules is not enough. You also have to enable it in listen → ejabberd_http → [request_handlers](listen-options.md#request_handlers). Both places. No cap, both. 🫶

And if you want a specific API version N, just slap a vN into the URL path when you define it in the request_handlers. Example: /api/v2: mod_http_api.

To actually run a command, you send a POST request to the matching URL:

http://localhost:5280/api/COMMAND-NAME

Available options:

default_version: integer() | string() — note about this option: added in 24.12. This is the API version used when the URL path doesn't say which one you want. If you set an ejabberd version in here, it'll use the latest API version that was available in that ejabberd version. So for example, setting "24.06" in this option implies 2. The default value is the latest version. 💅

Example:

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      /api: mod_http_api

modules:
  mod_http_api:
    default_version: 2

🎀 `mod_http_fileserver`

note about this option: improved docroot in 26.01.

A simple lil' module that serves files from the local disk over HTTP. That's it, that's the whole vibe. 🍓

Available options:

accesslog: Path — file where accesses get logged, in an Apache-like format. If you don't specify this option, literally nothing gets logged. Silence. 🙈
content_types: {Extension: Type} — lets you map extensions to content types. Several content types are already defined, and with this option you can add new definitions or modify existing ones. The default values are:
custom_headers: {Name: Value} — custom HTTP headers to include in all responses. There are no custom headers by default.
default_content_type: Type — the content type used for unknown extensions. Default value is application/octet-stream.
directory_indices: [Index, ...] — one or more directory index files, just like Apache's DirectoryIndex variable. When an HTTP request hits a directory instead of a regular file, those directory indices get checked in order, and the first one found is returned. Default value is an empty list.
docroot: PathDir | {PathURL, PathDir} — note about this option: improved in 26.01. The directory to serve files from, or a map with several URL paths (as specified in [request_handlers](listen-options.md#request_handlers)) and their matching directories. This is a mandatory option. 👑
must_authenticate_with: [{Username, Hostname}, ...] — the list of accounts that are allowed to use this service. Default value: [].

Example (the content_types defaults, verbatim):

content_types:
  .avi: video/avi
  .bmp: image/bmp
  .bz2: application/x-bzip2
  .css: text/css
  .gif: image/gif
  .gz: application/x-gzip
  .html: text/html
  .ico: image/vnd.microsoft.icon
  .jar: application/java-archive
  .jpeg: image/jpeg
  .jpg: image/jpeg
  .js: text/javascript
  .json: application/json
  .m4a: audio/mp4
  .map: application/json
  .mp3: audio/mpeg
  .mp4: video/mp4
  .mpeg: video/mpeg
  .mpg: video/mpeg
  .ogg: application/ogg
  .pdf: application/pdf
  .png: image/png
  .rtf: application/rtf
  .svg: image/svg+xml
  .tiff: image/tiff
  .ttf: font/ttf
  .txt: text/plain
  .wav: audio/wav
  .wasm: application/wasm
  .webp: image/webp
  .woff: font/woff
  .woff2: font/woff2
  .xml: application/xml
  .xpi: application/x-xpinstall
  .xul: application/vnd.mozilla.xul+xml
  .xz: application/x-xz
  .zip: application/zip

docroot as a map, example:

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      /pub/content: mod_http_fileserver
      /share: mod_http_fileserver
      /: mod_http_fileserver
modules:
  mod_http_fileserver:
    docroot:
      /pub/content: /var/service/www
      /share: /usr/share/javascript
      /: /var/www

Examples:

This example configuration will serve the files from the local directory /var/www at the address http://example.org:5280/pub/content/. In this example a new content type ogg is defined, png is redefined, and the jpg definition is deleted:

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      /pub/content: mod_http_fileserver

modules:
  mod_http_fileserver:
    docroot: /var/www
    accesslog: /var/log/ejabberd/access.log
    directory_indices:
      - index.html
      - main.htm
    custom_headers:
      X-Powered-By: Erlang/OTP
      X-Fry: "It's a widely-believed fact!"
    content_types:
      .ogg: audio/ogg
      .png: image/png
    default_content_type: text/html

Fr fr, that X-Fry header is iconic and I will not be taking questions. 😭

🦋 `mod_http_upload`

note about this option: added content_types in 26.01.

This module lets clients request permission to upload a file via HTTP, exactly as described in XEP-0363: HTTP File Upload. If the request is accepted, the client gets a URL for uploading the file — plus another URL where that file can be downloaded later. Two URLs, one slay. ✨

To use this module, it must be enabled in listen → ejabberd_http → [request_handlers](listen-options.md#request_handlers).

Available options:

access: AccessName — defines the access rule limiting who's allowed to use the HTTP upload service. The default value is local. And listen: if no access rule with that name exists, no user will be allowed to use the service. 💀
append_module_config: {UploadHost: Options} — note about this option: added in 26.07. Adds a few specific options to a certain upload host that was previously defined in the mod_http_upload hosts option. Right now only name and vcard can be defined here. It's similar to the toplevel append_host_config option, but in this case it's applied to this module's options.
content_types: {Extension: Type} — note about this option: added in 26.01. Mappings of extension to content type, just like the content_types option of mod_http_fileserver.
custom_headers: {Name: Value} — extra header fields to include in all HTTP responses. By default no custom headers are included.
dir_mode: Permission — the permission bits of the docroot directory and any directories created during file uploads. Bits are given as an octal number (see the chmod(1) manual page) inside 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 given here (as an absolute path). 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 one makes it possible to offload all HTTP Upload processing to a separate HTTP server. Both ejabberd and that HTTP server should share this secret and behave exactly as described at Prosody's mod_http_upload_external: Implementation. There is no default value.
file_mode: Permission — the permission bits of uploaded files. Bits are given as an octal number (see the chmod(1) manual page) inside double quotes. For example: "0644". The default is undefined, which means no explicit permissions will be set.
get_url: URL — the initial part of the GET URLs used for downloading files. The default value is undefined. When this option is undefined, it gets set to the same value as put_url. The keyword @HOST@ is replaced with the virtual host name. NOTE: if GET requests are handled by this module, get_url must match 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. (Yes bestie, deprecated deprecated. Don't.)
hosts: [Host, ...] — the Jabber IDs of the service. If the hosts option isn't 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 set to node, the node identifier of the user's JID (i.e., the user name) gets 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.

append_module_config example:

modules:
  mod_http_upload:
    hosts:
      - service1.@HOST@
      - service2.@HOST@
    name: "Service General"
    append_module_config:
      service1.localhost:
        name: "Service 1"
      service2.example.net:
        name: "Service 2"

max_size: Size — caps how big a file is even allowed to be, bestie. you gotta give it either a byte count (and it has to be larger than zero, no funny business) or the word infinity. default is 104857600. 💖
name: Name — the name your service shows up under in Service Discovery. default is "HTTP File Upload". fair warning tho: only some XMPP clients actually bother displaying it 🙈
put_url: URL — sets the front bit of the PUT URLs used for uploads. two magic keywords live here: @HOST@ gets swapped for the virtual host name, and @HOST_URL_ENCODE@ gets swapped for the host name encoded for URL — which is literally your saving grace when your virtual hosts have non-latin characters in them. default is "https://@HOST@:5443/upload".

⚠️ ok important: different virtual hosts cannot use the same PUT URL. like, at all. no cap.

rm_on_unregister: true | false — decides whether files a user uploaded get yeeted when that user gets unregistered. default is true (yes, it cleans up after itself, slay).
secret_length: Length — how long the random string inside the GET and PUT URLs that mod_http_upload generates should be. minimum is 8 characters but honestly? go bigger, it's giving security 💅. default is 40.
service_url — deprecated. that's it, that's the whole thing. she's retired 🫶
thumbnail: true | false — tells ejabberd whether it should make thumbnails of uploaded images. if it does, a <thumbnail/> element comes back with the PUT response, containing the download <uri/> plus some metadata. default is false.
vcard: vCard — a custom vCard for the service, which some XMPP clients will show off in Service Discovery. the value is a YAML map built from the XML representation of a vCard. since that representation has no attributes, the mapping is literally straightforward, no mental gymnastics required ✨

Example:

# This XML representation of vCard:
#   <vCard xmlns='vcard-temp'>
#     <FN>Conferences</FN>
#     <ADR>
#       <WORK/>
#       <STREET>Elm Street</STREET>
#     </ADR>
#   </vCard>
#
# is translated to:
vcard:
  fn: Conferences
  adr:
    -
      work: true
      street: Elm Street

Example:

listen:
  -
    port: 5443
    module: ejabberd_http
    tls: true
    request_handlers:
      /upload: mod_http_upload

modules:
  mod_http_upload:
    docroot: /ejabberd/upload
    put_url: "https://@HOST@:5443/upload"

🌸 `mod_http_upload_quota` 🌸

this module adds quota support for mod_http_upload. she's the responsible bestie who makes sure nobody eats the whole disk 🍓

this module depends on mod_http_upload. like, don't try to run her solo, it won't go well.

Available options:

access_hard_quota: AccessName — picks which access rule defines the "hard quota" for the matching JIDs. that rule has to yield a positive number for any JID that's supposed to have a quota limit — and that number is the count of megabytes the corresponding user may upload. when the threshold gets exceeded, ejabberd starts deleting the oldest files uploaded by that user, and keeps going until their disk usage equals or falls below the specified soft quota (peep option access_soft_quota too). default value is hard_upload_quota.
access_soft_quota: AccessName — same deal but for the "soft quota". the rule must yield a positive number of megabytes for any JID that's supposed to have a quota limit. for the details, go read the description of the access_hard_quota option, it's all there 👑. default value is soft_upload_quota.
max_days: Days — if you give it a number larger than zero, then any files (and directories, yes, those too) older than that many days get removed from the subdirectories of the docroot directory, once per day. default value is infinity.

Examples:

🫶 heads up: it's not necessary to specify the access_hard_quota and access_soft_quota options in order to use the quota feature. you can just stick to the default names and only specify access rules, like the ones in this example:

shaper_rules:
  soft_upload_quota:
    1000: all # MiB
  hard_upload_quota:
    1100: all # MiB

modules:
  mod_http_upload: {}
  mod_http_upload_quota:
    max_days: 100

🦋 `mod_invites` 🦋

📌 note about this option: improved in 26.07. (glow up!!)

lets User Invitation and Account Creation make out-of-band links to onboard other people onto the XMPP network and establish a mutual subscription. this implements XEP-0379: Pre-Authenticated Roster Subscription, XEP-0401: Ad-hoc Account Invitation Generation, and XEP-0445: Pre-Authenticated In-Band Registration. it's giving ✨recruitment era✨

these invitations get created as XMPP URIs, either via ad-hoc commands or via API commands (like generate_invite API and generate_invite_with_username API), and they're then meant to be sent out-of-band.

the receiving user should have a client installed that supports those invitations. and since that has proven to be a common obstacle for easy adoption (😭 real), this module comes with an optional landing page parameter — which can be some external service like an installation of easy-xmpp-invitation, a third-party service like JoinJabber, or, for convenience, a built-in service. that landing page then guides the recipient through setting up a client and creating an account if required. so helpful, honestly.

to use the included landing page feature, you have to set landing_page to either auto or an URL template like https://{{ host }}/invites/{{ invite.token }} if your server setup includes a so called reverse proxy. and you also need to connect this module as a handler of an ejabberd_http listener, as shown in the example below. both things, not one. both.

for convenience there's now also a start page included, at wherever you mount mod_invites at the ejabberd_http handler. this start page lets people generate invites by giving their username and password. as such the URL should be protected by HTTPS (please, bestie, protect it). main use-case? when people only have clients that don't support generating invites natively. periodt.

if you'd rather use an external service, set landing_page to something like http://{{ host }}:8080/easy-xmpp-invites/#{{ invite.uri|strip_protocol }} or https://invite.joinjabber.org/#{{ invite.uri|strip_protocol }}.

Available options:

access_create_account: Access Rule Name — the name of an access rule specifying who's allowed to create invites of create account. default value is none, i.e. nobody is able to create such invites. plus it applies to roster invites and allows doing in-band registration (IBR) if the sending user is allowed by this rule. and users from the admin ACL are always allowed to create those invites, no questions asked 👑

Example:

mod_invites:
  access_create_account: local

db_type: mnesia | sql — same as the top-level default_db option, but applied to this module only.
landing_page: none | auto | LandingPageURLTemplate — whether or not to use a landing page for the invites that are being created. if you're using a template URL, it can be either external or internal. template variables include host, invite.token and invite.uri, and there are filters defined too — most notably strip_protocol. here's an example: http://{{ host }}:8080/easy-xmpp-invites/#{{ invite.uri|strip_protocol }}. for convenience you can choose auto and the ejabberd_http handler for mod_invites will be used to construct the landing page URL. default is none.
max_invites: pos_integer() | infinity — the max number of create account invites that one individual user can create. users that match the admin ACL are exempt from this limitation (they're built different 💅). plus it restricts the use of roster invites for account creation. default is infinity.
site_name: Site Name — a human readable name for your site. e.g. "My Beautiful Laundrette". used in landing page templates. cute.
templates_dir: Path — the directory containing templates and static files used for the landing page and web registration form. you only need to set this if you want to ship your own set of templates or list of recommended apps. iykyk.
token_expire_seconds: pos_integer() — number of seconds until the token expires. default value is 432000 (that is five days: 5 * 24 * 60 * 60).
webchat_url: none | auto | Webchat URL — 📌 note about this option: added in 26.03. URL to a webchat client. upon manual registration through the web-form this will be recommended in order to get started. if auto is chosen, we pick the mod_conversejs from the listeners section. default is auto.

Examples:

basic configuration with landing page but without creating accounts, just roster invites:

listen:
  -
    port: 5281
    module: ejabberd_http
    request_handlers:
      /invites: mod_invites
# [...]
modules:
  mod_invites:
    landing_page: auto

to allow only admin users to create invites of create account and disable regular in-band registration, you'd have a config like this:

acl:
  admin:
    - user: "my_admin_user@example.com"

access_rules:
  register:
    allow: admin

modules:
  mod_invites:
    landing_page: auto
  mod_register:
    allow_modules:
      - mod_invites

if you want all your users to be able to send create account invites, you'd configure your server like this instead. note that the names of the access rules are just examples and you're free to change them 🎀

acl:
  local:
    user_regexp: ""
access_rules:
  create_account_invite:
    allow: local

modules:
  mod_invites:
    access_create_account: create_account_invite
    landing_page: auto
  mod_register:
    allow_modules:
      - mod_invites

🌈 `mod_jidprep`

Okay so this one is genuinely so useful — it lets XMPP clients ask the server to normalize a JID according to the rules in RFC 6122: XMPP Address Format. Bestie, that's lowkey a lifesaver for clients stuck in certain constrained environments, and it's also iconic for testing purposes. 💅

Available options:

access: AccessName — tells you which access rule decides who gets to use this service. The default value is local.

🎀 `mod_last`

This module adds support for XEP-0012: Last Activity. It's giving "detective era" — you can use it 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. Obsessed. ✨

Available options:

cache_life_time: timeout() — Same as top-level cache_life_time option, but applied to this module only.
cache_missed: true | false — Same as top-level cache_missed option, but applied to this module only.
cache_size: pos_integer() | infinity — Same as top-level cache_size option, but applied to this module only.
db_type: mnesia | sql — Same as top-level default_db option, but applied to this module only.
use_cache: true | false — Same as top-level use_cache option, but applied to this module only.

🦋 `mod_legacy_auth`

The module implements XEP-0078: Non-SASL Authentication.

Note 🫶 This type of authentication was obsoleted in 2008 and you unlikely need this module unless you have something like outdated Jabber bots.

The module has no options. Literally zero. Nothing. Empty. A whole vibe of nothingness. 💀

👑 `mod_mam`

This module implements XEP-0313: Message Archive Management and XEP-0441: Message Archive Management Preferences. Compatible XMPP clients can use it to store their chat history on the server. It's giving "the server remembers everything so you don't have to" energy. 🌸

Note 😭 Mnesia backend for mod_mam is not recommended: it's limited to 2GB and often gets corrupted when reaching this limit. SQL backend is recommended. Namely, for small servers SQLite is a preferred choice because it's very easy to configure. Do not come for me, this is literally what the docs say.

Available options:

access_preferences: AccessName — this access rule defines who is allowed to modify the MAM preferences. The default value is all.
archive_muc_as_mucsub: true | false — Note about this option: added in 25.10. When this option is enabled, incoming groupchat messages for users that have mucsub subscription to a room from which message originated will have those messages archived after being converted to mucsub event messages. The default value is false.
assume_mam_usage: true | false — this option determines how ejabberd's stream management code (see mod_stream_mgmt) handles unacknowledged messages when the connection is lost. Usually, such messages are either bounced or resent. However, neither is done for messages that were stored in the user's MAM archive if this option is set to true. In this case, ejabberd assumes those messages will be retrieved from the archive. The default value is false.
cache_life_time: timeout() — Same as top-level cache_life_time option, but applied to this module only.
cache_missed: true | false — Same as top-level cache_missed option, but applied to this module only.
cache_size: pos_integer() | infinity — Same as top-level cache_size option, but applied to this module only.
clear_archive_on_room_destroy: true | false — whether to destroy message archive of a room (see mod_muc) when it gets destroyed. The default value is true.
compress_xml: true | false — when enabled, new messages added to archives are compressed using a custom compression algorithm. This feature works only with SQL backends. The default value is false.
db_type: mnesia | sql — Same as top-level default_db option, but applied to this module only.
default: always | never | roster — the option defines default policy for chat history. When always is set every chat message is stored. With roster only chat history with contacts from user's roster is stored. And never fully disables chat history. Note that a client can change its policy via protocol commands. The default value is never.
request_activates_archiving: true | false — if the value is true, no messages are stored for a user until their client issue a MAM request, regardless of the value of the default option. Once the server received a request, that user's messages are archived as usual. The default value is false.
use_cache: true | false — Same as top-level use_cache option, but applied to this module only.
user_mucsub_from_muc_archive: true | false — when this option is disabled, for each individual subscriber a separate mucsub message is stored. With this option enabled, when a user fetches archive virtual mucsub, messages are generated from muc archives. The default value is false.

API Tags: ../../developer/ejabberd-api/admin-tags.md#mam|mam, ../../developer/ejabberd-api/admin-tags.md#purge|purge

💜 `mod_matrix_gw`

Note about this option: improved in 25.08.

Matrix gateway, bestie!! ✨ Supports room versions 9, 10 and 11 since ejabberd 25.03; room versions 4 and higher since ejabberd 25.07; room version 12 (hydra rooms) since ejabberd 25.08. Erlang/OTP 25 or higher is required to use this module. This module is available since ejabberd 24.02. She's been around a minute and she keeps leveling up. 🔥

Available options:

host: Host — this option defines the Jabber IDs of the service. If the host option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix "matrix.". The keyword @HOST@ is replaced with the real virtual host name.
key: string() — value of the matrix signing key, in base64.
key_name: string() — name of the matrix signing key.
leave_timeout: integer() — delay in seconds between a user leaving a MUC room and sending leave Matrix event.
matrix_domain: Domain — specify a domain in the Matrix federation. The keyword @HOST@ is replaced with the hostname. The default value is @HOST@.
matrix_id_as_jid: true | false — if set to true, all packets failing to be delivered via an XMPP server-to-server connection will then be routed to the Matrix gateway by translating a Jabber ID user@matrixdomain.tld to a Matrix user identifier @user:matrixdomain.tld. When set to false, messages must be explicitly sent to the matrix gateway service Jabber ID to be routed to a remote Matrix server. In this case, to send a message to Matrix user @user:matrixdomain.tld, the client must send a message to the JID user%matrixdomain.tld@matrix.myxmppdomain.tld, where matrix.myxmppdomain.tld is the JID of the gateway service as set by the host option. The default is false.
notary_servers: [Server, ...] — a list of notary servers.

Example — look at her go 🫶:

listen:
  -
    port: 8448
    module: ejabberd_http
    tls: true
    request_handlers:
      "/_matrix": mod_matrix_gw

modules:
  mod_matrix_gw:
    key_name: "key1"
    key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    matrix_id_as_jid: true

⭐ `mod_metrics`

This module sends events to external backend (by now only grapherl is supported). Supported events are:

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. It's literally just counting vibes and shipping them out. 💅

Available options:

ip: IPv4Address — IPv4 address where the backend is located. The default value is 127.0.0.1.
port: Port — an internet port number at which the backend is listening for incoming connections/packets. The default value is 11111.

🧚 `mod_mix`

Note about this option: added in 16.03 and improved in 19.02.

This module is an experimental implementation of XEP-0369: Mediated Information eXchange (MIX). It's asserted that the MIX protocol is going to replace the MUC protocol in the future (see mod_muc). So like, future energy, but experimental future energy, okay? 🙈

To learn more about how to use that feature, you can refer to our tutorial: ../../tutorials/mix-010.md|Getting started with MIX

The module depends on mod_mam. Yes, she needs her friend. 🫶

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. Like, respectfully, move on. 💀
hosts: [Host, ...] — this option defines the Jabber IDs of the service. If the hosts option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "mix.". The keyword @HOST@ is replaced with the real virtual host name.
name: Name — a name of the service in the Service Discovery. This will only be displayed by special XMPP clients. The default value is Channels.

🌸 `mod_mix_pam`

This module implements XEP-0405: Mediated Information eXchange (MIX): Participant Server Requirements. The module is needed if MIX compatible clients on your server are going to join MIX channels (either on your server or on any remote servers). Local or remote, she doesn't gatekeep. ✨

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. So like, technically optional, practically please don't skip her.

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 — literally the same thing as the top-level default_db option, just scoped to this module only 💅
use_cache: true | false — same as the top-level use_cache option, but again, this module's vibe only ✨

🦋 `mod_mqtt` 🦋

Okay so this one adds ../guide/mqtt/index.md|support for the MQTT protocol version 3.1.1 and 5.0 — periodt. But bestie, listen: remember to configure mod_mqtt in both the modules and listen sections or it's giving nothing 💀

Available options, let's go 👑

access_publish: {TopicFilter: AccessName} — access rules that restrict who can publish to which topics. No restrictions by default, so it's a free-for-all until you say otherwise 🙈
access_subscribe: {TopicFilter: AccessName} — same energy but for subscribers. Also zero restrictions by default 🎀
cache_life_time: timeout() — same as the top-level cache_life_time option, but applied to this module only ⭐
cache_missed: true | false — same as the top-level cache_missed option, but for this module only 💜
cache_size: pos_integer() | infinity — same as the top-level cache_size option, applied to this module only 🌸
db_type: mnesia | sql — same as the top-level default_db option, applied to this module only 🫶
match_retained_limit: pos_integer() | infinity — caps how many retained messages get returned to a client when it subscribes to some topic filter. Default is 1000 🔥
max_queue: Size — maximum queue size for outgoing packets. Default is 5000 👑
max_topic_aliases: 0..65535 — the max number of aliases a client can associate with topics. Default is 100 ✨
max_topic_depth: Depth — the max topic depth, aka the number of slashes (/) in the topic. Default is 8 🦋
queue_type: ram | file — same as the top-level queue_type option, but applied to this module only 💖
ram_db_type: mnesia — same as the top-level default_ram_db option, but applied to this module only 🌈
session_expiry: timeout() — how long to wait for an MQTT session resumption. If you set it to 0, the session gets destroyed the moment the underlying client connection closes. Default is 5 minutes ⏳
use_cache: true | false — same as the top-level use_cache option, but applied to this module only 🎀

🔥 `mod_mqtt_bridge` 🔥

This icon lets you sync local MQTT topics with data sitting on remote servers. It can push topic updates to remote servers whenever a local user updates a local topic, or it can subscribe to changes on a remote server and update the local copy when the remote data changes. Available since ejabberd 23.01, ngl it's lowkey underrated 💅

Available options:

replication_user: JID — the identifier of the user that gets assigned as owner of local changes 👑
servers: {ServerUrl: {Key: Value}} — declares what data to share for each ServerUrl. Server URLs can use these schemas: mqtt, mqtts (mqtt with tls), mqtt5, mqtt5s (both of these trigger v5 protocol), ws, wss, ws5, wss5 🌐 The keys must be:
- authentication: {AuthKey: AuthValue} — a list of authentication info, where AuthKey can be the username and password fields, or certfile pointing to a client certificate. Heads up bestie: certificate authentication only works with mqtts, mqtt5s, wss, wss5 🎀
- publish: {LocalTopic: RemoteTopic} — either publish or subscribe must be set, or both ✨
- subscribe: {RemoteTopic: LocalTopic} — either publish or subscribe must be set, or both ✨

Example, slay:

modules:
  mod_mqtt_bridge:
    replication_user: "mqtt@xmpp.server.com"
    servers:
      "mqtt://server.com":
        authentication:
          certfile: "/etc/ejabberd/mqtt_server.pem"
        publish:
          "localA": "remoteA" # local changes to 'localA' will be replicated on remote server as 'remoteA'
          "topicB": "topicB"
        subscribe:
          "remoteB": "localB" # changes to 'remoteB' on remote server will be stored as 'localB' on local server

👑 `mod_muc` 👑

Note about this option: incorporated mod_muc_occupantid in 26.02 🫶

This module is the whole Multi-User Chat (MUC) situation — users can discover existing rooms, join them, or create their own. Occupants of a room can chat in public or have private chats. Main character energy fr fr 💖

Protocols implemented in this module:

XEP-0045: Multi-User Chat
XEP-0249: Direct MUC Invitations
XEP-0421: Occupant identifiers for semi-anonymous MUCs
XEP-0486: MUC Avatars
Muc/Sub: Multi-User Chat Subscriptions

The MUC service lets any Jabber ID register a nickname, so nobody else can steal that nickname in any room across the whole MUC service. To register a nickname, open the Service Discovery in your XMPP client and register in the MUC service ✨

You can also register a nickname in a room, so nobody else can use that nickname in that room. And here's the tea: if a nick is registered in the MUC service, it can't be registered in any room, and vice versa — a nick registered in a room can't be registered at the MUC service. Mutual exclusivity, we love to see it 💅

This module supports clustering and load balancing. One module can be started per cluster node. Rooms are distributed at creation time across all available MUC module instances. The multi-user chat module is clustered, but the rooms themselves are not clustered and not fault-tolerant: if the node managing a set of rooms goes down, those rooms disappear 😭 and they'll be recreated on an available node on the first connection attempt.

Available options:

access: AccessName — you can specify who's allowed to use the Multi-User Chat service. By default, everyone is allowed 🌈
access_admin: AccessName — specifies who's allowed to administrate the Multi-User Chat service. Default is none, which means only the room creator can administer their own room. Administrators can send a normal message to the service JID and it'll show up in all active rooms as a service message. They can also send a groupchat message to the JID of an active room, and it'll be shown in that room as a service message 👑
access_create: AccessName — configures who's allowed to create new rooms at the Multi-User Chat service. Default is all, meaning everyone can create rooms 🎀
access_mam: AccessName — configures who's allowed to modify the mam room option. Default is all, meaning everyone's allowed to modify it 🦋
access_persistent: AccessName — configures who's allowed to modify the persistent room option. Default is all, meaning everyone's allowed to modify it 🌸
access_register: AccessName — specifies who's allowed to register a nickname within the Multi-User Chat service and rooms.

Note about this option: improved in 23.10. The default is all for backward compatibility, meaning any user is allowed to register any free nick in the MUC service and in the rooms 💖

append_module_config: {MUCHost: Options} — add a few specific options to a certain MUC host that was previously defined in the mod_muc hosts option. It's similar to the toplevel append_host_config option, but here it applies to the mod_muc options instead.

Note about this option: added in 26.07 ✨

Example:

modules:
  mod_muc:
    hosts:
      - service1.@HOST@
      - service2.@HOST@
    name: "Service General"
    append_module_config:
      service1.localhost:
        name: "Service 1"
      service2.example.net:
        name: "Service 2"

cleanup_affiliations_on_start: true | false — removes affiliations for non-existing local users on startup. Default is false.

Note about this option: added in 22.05 🧹

db_type: mnesia | sql — same as the top-level default_db option, but applied to this module only 💜
default_room_options: Options — defines the default room options. Just so you know, the creator of a room can modify their room's options at any time using an XMPP client with MUC capability 👑 The Options are:
- allow_change_subj: true | false — allow occupants to change the subject. Default is true 🎀
- allow_private_messages_from_visitors: anyone | moderators | nobody — visitors can send private messages to other occupants. Default is anyone, meaning visitors can DM any occupant 🙈
- allow_query_users: true | false — occupants can send IQ queries to other occupants. Default is true ✨
- allow_subscription: true | false — allow users to subscribe to room events as described in ../../developer/xmpp-clients-bots/extensions/muc-sub.md|Multi-User Chat Subscriptions. Default is false 🌸
- allow_user_invites: true | false — allow occupants to send invitations. Default is false 💌
- allow_visitor_nickchange: true | false — allow visitors to change their nickname. Default is true 💅
- allow_visitor_status: true | false — allow visitors to send status text in presence updates. If disallowed, the status text gets stripped before the presence update is broadcast to all room occupants. Default is true ✂️
- allow_voice_requests: true | false — allow visitors in a moderated room to request voice. Default is true 🎤
- allowpm: anyone | participants | moderators | none — who can send private messages. Default is anyone 💬
- anonymous: true | false — the room is anonymous, so occupants don't see the real JIDs of other occupants. Note that room moderators can always see the real JIDs of the occupants. Default is true 🕵️‍♀️
captcha_protected: true | false — if a user tries to join a room where they have, like, no affiliation (not an owner, not an admin, not a member), the room hits them with a CAPTCHA challenge before letting them in — see the section basic.md#captcha|CAPTCHA. The default value is false. 🧚
description: Room Description — a short lil description of the room. The default value is an empty string.
enable_hats: true | false — note about this option: improved in 25.10 ✨ It allows extended roles as defined in XEP-0317: Hats. For ejabberd older than 25.10, go peek at the ../../tutorials/muc-hats.md|MUC Hats page. The default value is true.
lang: Language — the preferred language for the discussions happening in the room. The language format should conform to RFC 5646. There is no value by default.
logging: true | false — the public messages get logged using mod_muc_log. The default value is false.
mam: true | false — enables message archiving. This implies mod_mam is enabled. The default value is false.
max_users: Number — maximum number of occupants allowed in the room. The default value is 200.
members_by_default: true | false — the occupants who enter the room are participants by default, so they get "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 — the password of the room. This implies the option password_protected is set to true. There is no default value.
password_protected: true | false — the password is required to enter the room. The default value is false.
persistent: true | false — the room persists even if the last participant leaves. The default value is false.
presence_broadcast: [Role] — a list of roles whose presence gets 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 anyone to actually enter the room. The default value is true.
pubsub: PubSub Node — XMPP URI of the associated Publish/Subscribe node. The default value is an empty string.
title: Room Title — a human-readable title of the room. There is no default value 💅
vcard: vCard — a custom vCard for the room. See the equivalent mod_muc option. The default value is an empty string.
vcard_xupdate: undefined | external | AvatarHash — sets the hash of the avatar image. The default value is undefined.
voice_request_min_interval: Number — minimum interval between voice requests, in seconds. The default value is 1800.

hibernation_timeout: infinity | Seconds — timeout before hibernating the room process, expressed in seconds. The default value is infinity.
history_size: Size — okay so a small history of the current discussion gets sent to users when they enter the room. With this option you define the number of history messages to keep and send to users joining the room. The value is a non-negative integer. Setting the value to 0 disables the history feature and, as a result, nothing is kept in memory. The default value is 20. This value affects all rooms on the service. NOTE: modern XMPP clients rely on Message Archives (XEP-0313), so feel free to disable the history feature if you’re only using modern clients and have mod_mam module loaded. 🦋
host — Deprecated. Use hosts instead.
hosts: [Host, ...] — this option defines the Jabber IDs of the service. If the hosts option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "conference.". The keyword @HOST@ is replaced with the real virtual host name.
max_captcha_whitelist: Number — note about this option: added in 21.01 This option defines the maximum number of characters that Captcha Whitelist can have when configuring the room. The default value is infinity.
max_password: Number — note about this option: added in 21.01 This option defines the maximum number of characters that Password can have when configuring the room. The default value is infinity.
max_room_desc: Number — this option defines the maximum number of characters that Room Description can have when configuring the room. The default value is infinity.
max_room_id: Number — this option defines the maximum number of characters that Room ID can have when creating a new room. The default value is infinity.
max_room_name: Number — this option defines the maximum number of characters that Room Name can have when configuring the room. The default value is infinity.
max_rooms_discoitems: Number — when there are more rooms than this Number, only the non-empty ones are returned in a Service Discovery query. The default value is 100.
max_user_conferences: Number — this option defines the maximum number of rooms that any given user can join. The default value is 100. It's there 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 it 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's considered overcrowded. When a MUC room is considered overcrowded, presence broadcasts are limited to reduce load, traffic and the excessive presence "storm" received by participants. The default value is 1000.
min_message_interval: Number — this option defines the minimum interval between two messages sent 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 protect a MUC service from occupant abuses and limit the 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 sent 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 amount 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. It can protect a MUC service from occupant abuses. If an occupant tries to change their 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 the top-level queue_type option, but applied to this module only.
ram_db_type: mnesia | sql — same as the top-level default_ram_db option, but applied to this module only.
regexp_room_id: string() — this option defines the regular expression that a Room ID must satisfy to allow the room creation. The default value is the empty string.
room_shaper: none | ShaperName — this option defines shaper for the MUC rooms. The default value is none.
user_message_shaper: none | ShaperName — this option defines shaper for the users messages. The default value is none.
user_presence_shaper: none | ShaperName — this option defines shaper for the users presences. The default value is none.
vcard: vCard — a custom vCard of the service that will be displayed by some XMPP clients in Service Discovery. The value of vcard is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward. 🎀

Example:

                   # This XML representation of vCard:
                   #   <vCard xmlns='vcard-temp'>
                   #     <FN>Conferences</FN>
                   #     <ADR>
                   #       <WORK/>
                   #       <STREET>Elm Street</STREET>
                   #     </ADR>
                   #   </vCard>
                   #
                   # is translated to:
                   vcard:
                     fn: Conferences
                     adr:
                       -
                         work: true
                         street: Elm Street

`mod_muc_admin`

Okay so this one is lowkey the backstage pass for your local MUC services and all their MUC rooms 🎟️ — it gives you commands to administer them, plus some cute little WebAdmin pages so you can actually look at the rooms that exist instead of just vibing in the dark.

Heads up bestie: this module depends on mod_muc. No mod_muc, no party.

Available options:

subscribe_room_many_max_users (Number) — 🫶 note: added in 22.05. This is the cap on how many users can be subscribed to a room at once when you use the subscribe_room_many API. The default value is 50.

API Tags: ../../developer/ejabberd-api/admin-tags.md#muc|muc, ../../developer/ejabberd-api/admin-tags.md#muc_room|muc_room, ../../developer/ejabberd-api/admin-tags.md#muc_sub|muc_sub

`mod_muc_log`

This module ✨ optionally logs Multi-User Chat (MUC) public conversations to HTML. So once you enable it, users can join a room with a MUC capable XMPP client, and — if they've got enough privileges — they can pull up the configuration form and flip the option that turns room logging on. It's giving scrapbook but for group chats 📖

Features, and honestly, slay:

Room details get added on top of each page: room title, JID, author, subject and configuration. The whole vibe check up front 💅
The room JID in the generated HTML is a link to join the room (using XMPP URI). clickable. iconic.
Subject and room configuration changes are tracked and displayed.
Joins, leaves, nick changes, kicks, bans and /me are all tracked and displayed — including the reason, if there is one. receipts = kept 🧾
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. customize ur heart out 🎀
URLs on messages and subjects are converted to hyperlinks.
The timezone used on timestamps is shown on the log files.
A custom link can be added on top of each page.

And yes — the module depends on mod_muc.

Available options:

access_log (AccessName) — this 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 for it to take effect.
cssfile (Path | URL) — decides whether the HTML files should have a custom CSS file or just use the embedded CSS. Allowed values are either a Path to a local file or a URL to a remote file. By default a predefined CSS will be embedded into the HTML page.
dirname (room_jid | room_name) — configures 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. 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) — defines 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}) — 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:

file_permissions:
  mode: 644
  group: 33

outdir (Path) — 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, fr fr. The default value is www/muc.
spam_prevention (true | false) — if set to true, a special attribute is added to links that prevents their indexation by search engines. The default value is true, which means that nofollow attributes will be added to user submitted links. bye-bye crawlers 🚫🤖
timezone (local | universal) — the time zone for the logs. If set to local, the local time, as reported to the Erlang emulator by the operating system, will be used. Otherwise, UTC time will be used. The default value is local.
top_link ({URL: Text}) — lets you customize the link on the top right corner of each log file. The default value is shown in the example below:

top_link:
  /: Home

url (URL) — a top level URL where a client can access logs of a particular conference. The conference name is appended to the URL if the dirname option is set to room_name, or a conference JID is appended to the URL otherwise. There is no default value.

`mod_muc_rtbl`

⭐ note: added in 23.04.

This module implements Real-time blocklists for MUC rooms 🛡️ — it works by observing a remote pubsub node conforming with the specification described in https://xmppbl.org/. Very "security guard energy" of it, honestly.

Available options:

rtbl_node (PubsubNodeName) — the name of the pubsub node that should be used to track blocked users. The default value is muc_bans_sha256.
rtbl_server (Domain) — the domain of the XMPP server that serves the block list. The default value is xmppbl.org.

`mod_multicast`

This module implements a service for XEP-0033: Extended Stanza Addressing 📬 — one message, many destinations, no extra effort. main character service tbh.

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. (put it away bestie, we don't use it anymore)
hosts ([Host, ...]) — defines the Jabber IDs of the service. If the hosts option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "multicast.". The keyword @HOST@ is replaced with the real virtual host name. ⚠️ Please note: this module only uses the first vhost defined in this option.
limits (Sender: Stanza: Number) — specify a list of custom limits which override the default ones defined in XEP-0033. Limits are defined per sender type and stanza type, where:
- 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

`mod_offline`

This module implements XEP-0160: Best Practices for Handling Offline Messages and XEP-0013: Flexible Offline Message Retrieval 📥 Which basically means: every message sent to an offline user gets stored on the server until that user comes back online. So it's very similar to how email works — the server is holding your mail, bestie 💌

A user is considered offline if no session presence priority > 0 are currently open.

The delete_expired_messages API allows to delete expired messages, and the delete_old_messages API deletes older ones. 🗑️

Available options:

access_max_user_messages (AccessName) — defines which access rule will be enforced to limit the maximum number of offline messages that a user can have (their 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 used to disable an optimization that avoids bouncing error messages when groupchat messages could not be stored as offline. It will reduce chat room load, without any drawback in standard use cases. 🫶 You may change the default value only if you have a custom module which uses an offline hook after mod_offline. This option can be useful for both standard MUC and MucSub, but the bounce is much more likely to happen in the context of MucSub, so it is even more important to have it on large MucSub services. The default value is false, meaning the optimization is enabled.
cache_life_time (timeout()) — same as the top-level cache_life_time option, but applied to this module only.
cache_size (pos_integer() | infinity) — same as the top-level cache_size option, but applied to this module only.
db_type (mnesia | sql) — same as the top-level default_db option, but applied to this module only.
store_empty_body — true | false | unless_chat_state. Are we storing messages that have no <body/> element? The default is unless_chat_state, which means ejabberd stores messages even without <body/>, unless they only contain a chat state notification (as defined in XEP-0085: Chat State Notifications). 💅
store_groupchat — true | false. Do we store groupchat messages? Default is false.
use_cache — true | false. Same as the top-level use_cache option, but it only applies to this module.
use_mam_for_storage — true | false. This one is experimental, bestie. Enabling it makes this module use the archive table from mod_mam instead of its own spool table to retrieve messages received while the user was offline. It lets client developers slowly drop XEP-0160 and rely on XEP-0313 instead. It also further reduces storage when you enable MucSub. Known drawback for now: most flexible message retrieval queries don’t work — specifically those that allow retrieval/deletion of messages by id — but this specification is not widely used. Default is false to keep former behaviour as default.

Examples:

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
  ...

API Tags: ../../developer/ejabberd-api/admin-tags.md#offline|offline

🏓 mod_ping

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. NOTE: when mod_stream_mgmt is loaded and stream management is enabled by a client, this value is ignored, and the ack_timeout applies instead. Default is undefined.
ping_interval — timeout(). How often to send pings to connected clients, if 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. Default is 1 minute.
send_pings — true | false. If this is true, the server sends pings to connected clients that are not active in the interval defined in ping_interval. Useful to keep client connections alive or checking availability. Default is false.
timeout_action — none | kill. What to do when a client does not answer a server ping request in less than the period defined in ping_ack_timeout: kill means destroying the underlying connection, none means 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 to give the client a chance to resume it. Default is none.

Example:

modules:
  mod_ping:
    send_pings: true
    ping_interval: 4 min
    timeout_action: kill

🚨 mod_pres_counter

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 the time defined in interval. Please note that two users subscribing to each other usually generate 4 stanzas, so the recommended value is 4 or more. Default is 5.
interval — timeout(). The time interval. Default is 1 minute.

Example:

modules:
  mod_pres_counter:
    count: 5
    interval: 30 secs

🕵️ mod_privacy

This module implements XEP-0016: Privacy Lists. 🔐

📝 Note — Nowadays modern XMPP clients rely on XEP-0191: Blocking Command, which is implemented by mod_blocking. However, you still need mod_privacy loaded in order for mod_blocking to work.

Available options:

cache_life_time — timeout(). Same as the top-level cache_life_time option, but applied to this module only.
cache_missed — true | false. Same as the top-level cache_missed option, but applied to this module only.
cache_size — pos_integer() | infinity. Same as the top-level cache_size option, but applied to this module only.
db_type — mnesia | sql. Same as the top-level default_db option, but applied to this module only.
use_cache — true | false. Same as the top-level use_cache option, but applied to this module only.

🔒 mod_private

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).

It also implements the bookmark conversion described in XEP-0402: PEP Native Bookmarks, see bookmarks_to_pep API.

Available options:

cache_life_time — timeout(). Same as the top-level cache_life_time option, but applied to this module only.
cache_missed — true | false. Same as the top-level cache_missed option, but applied to this module only.
cache_size — pos_integer() | infinity. Same as the top-level cache_size option, but applied to this module only.
db_type — mnesia | sql. Same as the top-level default_db option, but applied to this module only.
use_cache — true | false. Same as the top-level use_cache option, but applied to this module only.

API Tags: ../../developer/ejabberd-api/admin-tags.md#private|private

👑 mod_privilege

Note about this option: improved in 24.10.

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:

iq — {Namespace: Options}. This option defines namespaces and their IQ permissions. By default no permissions are given. The Options are:
- both — AccessName. Allows sending IQ stanzas of type get and set. Default is none.
- get — AccessName. Allows sending IQ stanzas of type get. Default is none.
- set — AccessName. Allows sending IQ stanzas of type set. Default is none.
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. Default 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. Default 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. Default 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. Default is none.
- get — AccessName. Sets read access to a user’s roster. Default is none.
- set — AccessName. Sets write access to a user’s roster. Default is none.

Example:

modules:
  mod_privilege:
    iq:
      http://jabber.org/protocol/pubsub:
        get: all
    roster:
      get: all
    presence:
      managed_entity: all
    message:
      outgoing: all

📦 mod_providers

Note about this option: added in 25.08.

This module serves JSON provider files API v2 as described by XMPP Providers. 🦋

Okay so this module literally attempts to fill some properties gathering values automatically from your existing ejabberd configuration. Try enabling the module, check what values are displayed, and then customize using the options. It's giving auto-detect, but make it yours. ✨

To use this module, in addition to adding it to the modules section, you must also enable it in listen → ejabberd_http → listen-options.md#request_handlers|request_handlers. Notice you should set in listen.md#ejabberd_http|ejabberd_http the option listen-options.md#tls|tls enabled. Don't skip this step, bestie.

Available options:

alternativeJids: [string()] — List of JIDs (XMPP server domains) a provider offers for registration other than its main JID. The default value is [].
busFactor: integer() — Bus factor of the XMPP service (i.e., the minimum number of team members that the service could not survive losing) or -1 for n/a. The default value is -1.
freeOfCharge: true | false — Whether the XMPP service can be used for free. The default value is false.
languages: [string()] — List of language codes that your pages are available. Some options define URL where the keyword @LANGUAGE_URL@ will be replaced with each of those language codes. The default value is a list with the language set in the option language, for example: [en].
legalNotice: string() — Legal notice web page (per language). The keyword @LANGUAGE_URL@ is replaced with each language. The default value is "".
maximumHttpFileUploadStorageTime: integer() — Maximum storage duration of each shared file (number in days, 0 for no limit or -1 for less than 1 day). The default value is the same as option max_days from module mod_http_upload_quota, or 0 otherwise.
maximumHttpFileUploadTotalSize: integer() — Maximum size of all shared files in total per user (number in megabytes (MB), 0 for no limit or -1 for less than 1 MB). Attention: MB is used instead of MiB (e.g., 104,857,600 bytes = 100 MiB H 104 MB). This property is not about the maximum size of each shared file, which is already retrieved via XMPP. The default value is the value of the shaper value of option access_hard_quota from module mod_http_upload_quota, or 0 otherwise.
maximumMessageArchiveManagementStorageTime: integer() — Maximum storage duration of each exchanged message (number in days, 0 for no limit or -1 for less than 1 day). The default value is 0.
organization: string() — Type of organization providing the XMPP service. Allowed values are: company, "commercial person", "private person", governmental, "non-governmental" or "". The default value is "".
passwordReset: string() — Password reset web page (per language) used for an automatic password reset (e.g., via email) or describing how to manually reset a password (e.g., by contacting the provider). The keyword @LANGUAGE_URL@ is replaced with each language. The default value is an URL built automatically if mod_register_web is configured as a request_handler, or "" otherwise.
professionalHosting: true | false — Whether the XMPP server is hosted with good internet connection speed, uninterruptible power supply, access protection and regular backups. The default value is false.
serverLocations: [string()] — List of language codes of Server/Backup locations. The default value is an empty list: [].
serverTesting: true | false — Whether tests against the provider’s server are allowed (e.g., certificate checks and uptime monitoring). The default value is false.
since: string() — Date since the XMPP service is available. The default value is an empty string: "".
website: string() — Provider website. The keyword @LANGUAGE_URL@ is replaced with each language. The default value is "".

Example:

listen:
  -
    port: 443
    module: ejabberd_http
    tls: true
    request_handlers:
      /.well-known/xmpp-provider-v2.json: mod_providers

modules:
  mod_providers:
    alternativeJids: ["example1.com", "example2.com"]
    busFactor: 1
    freeOfCharge: true
    languages: [ag, ao, bg, en]
    legalNotice: "http://@HOST@/legal/@LANGUAGE_URL@/"
    maximumHttpFileUploadStorageTime: 0
    maximumHttpFileUploadTotalSize: 0
    maximumMessageArchiveManagementStorageTime: 0
    organization: "non-governmental"
    passwordReset: "http://@HOST@/reset/@LANGUAGE_URL@/"
    professionalHosting: true
    serverLocations: [ao, bg]
    serverTesting: true
    since: "2025-12-31"
    website: "http://@HOST@/website/@LANGUAGE_URL@/"

🦋 `mod_proxy65`

This module implements XEP-0065: SOCKS5 Bytestreams. It allows ejabberd to act as a file transfer proxy between two XMPP clients. Proxy era, but make it XMPP. 🫶

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.
append_module_config: {ProxyHost: Options} — Note about this option: added in 25.xx. Add a few specific options to a certain upload host previously defined in the mod_proxy65 hosts option. Right now only name and vcard can be defined here. This is similar to the toplevel append_host_config option, but in this case it’s applied to this module options.

Example:

modules:
  mod_proxy65:
    hosts:
      - service1.@HOST@
      - service2.@HOST@
    name: "Service General"
    append_module_config:
      service1.localhost:
        name: "Service 1"
      service2.example.net:
        name: "Service 2"

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.

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

🌸 `mod_pubsub`

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. Pubsub girlies, rise. 💜

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.
append_module_config: {PubSubHost: Options} — new drop, added in 26.07 ✨ This one lets you bolt a few extra options onto a specific PubSub host that you already defined up in mod_pubsub's hosts option. rn the only keys you can put here are name and vcard. It's basically the same energy as the top-level append_host_config option, except it applies to this module's options instead. 💅

Example:

modules:
  mod_pubsub:
    hosts:
      - service1.@HOST@
      - service2.@HOST@
    name: "Service General"
    append_module_config:
      service1.localhost:
        name: "Service 1"
      service2.example.net:
        name: "Service 2"

db_type: mnesia | sql — same vibe as the top-level default_db option, but it only applies to this module. no cap 🫶
default_node_config: List of Key:Value — use this to override the default node configuration no matter which node plugin is in play. The value is a list of key-value definitions. Important detail bestie: node configuration still uses the default configuration defined by the node plugin, and this configurable list just overrides whichever items you specify. 🎀
force_node_config: List of Node and the list of its Key:Value — defines the configuration for specific 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, bestie.
hosts: [Host, ...] — this option defines the Jabber IDs of the service. If you don't specify hosts, the only Jabber ID will be the hostname of the virtual host with the prefix "pubsub.". The keyword @HOST@ gets replaced with the real virtual host name. 💖
ignore_pep_from_offline: false | true — controls whether or not we should get last published PEP items from users in our roster who are offline when we connect. Value is true or false. If it's not defined, pubsub assumes true, so we only get the last items of online contacts. 👑
last_item_cache: false | true — whether pubsub should cache last items. Value is true or false. If it's not defined, pubsub does not cache last items. On systems with not so many nodes, caching last items speeds up pubsub and lets you raise the user connection rate. The cost? Memory usage, because every item is stored in memory. 💀
max_item_expire_node: timeout() | infinity — added in 21.12 🦋 specifies the maximum item expiry time. Default value is infinity.
max_items_node: non_neg_integer() | infinity — 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 — the maximum number of subscriptions managed by a node. Default 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 — picks which nodetree to use. If it's not defined, the default pubsub nodetree is used: tree. Only one nodetree can be used per host, and it's shared by all node plugins.
- tree nodetree stores 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 the database. This saves resources on systems with tons of nodes. If you're using the virtual nodetree, you can only enable these node plugins: [flat, pep] or [flat] — any other plugins configuration will not work. Also, all nodes will have the default configuration, and this can't be changed. Using virtual nodetree requires starting from a clean database — it will not work if you used the default tree nodetree before. 😭
pep_mapping: List of Key:Value — here you can hand over a list of key-value pairs to choose defined node plugins on a 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, ...] — specifies which pubsub node plugins to use. The first one in the list is used by default. If this option isn't defined, the default plugins list is [flat]. PubSub clients can define which plugin to use when creating a node: just add a type='plugin-name' attribute to the create stanza element. 💅
- flat plugin handles the default behaviour and follows the standard XEP-0060 implementation.
- pep plugin adds an extension to handle Personal Eventing Protocol (XEP-0163) to the PubSub engine. When it's enabled, PEP is handled automatically. ⭐
vcard: vCard — a custom vCard of the server that some XMPP clients will display in Service Discovery. The value of vCard is a YAML map constructed from an XML representation of vCard. Since that representation has no attributes, the mapping is straightforward. 🎀

Example:

# This XML representation of vCard:
#   <vCard xmlns='vcard-temp'>
#     <FN>Conferences</FN>
#     <ADR>
#       <WORK/>
#       <STREET>Elm Street</STREET>
#     </ADR>
#   </vCard>
#
# is translated to:
vcard:
  fn: Conferences
  adr:
    -
      work: true
      street: Elm Street

💖 Examples 💖

Example of a 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 a relational database requires using mod_pubsub with db_type: sql. Only the flat, hometree and pep plugins support SQL. The following example shows the 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

API Tags: ../../developer/ejabberd-api/admin-tags.md#purge|purge

🦋 `mod_pubsub_serverinfo` 🦋

added in 25.07 ✨ This module adds support for XEP-0485: PubSub Server Information, exposing S2S information over the Pub/Sub service.

Active S2S connections get published to a local PubSub node. rn the node name is hardcoded as "serverinfo". 👑

Connections that support this feature are exposed with their domain names, otherwise they show up as anonymous nodes. At startup a list of well known public servers is fetched — those are not shown as anonymous even if they don't support this feature. 🌈

⚠️ okay bestie, important: the module only shows S2S connections that were established while the module is running. If you install the module at runtime, run the stop_s2s_connections API or restart ejabberd to force S2S reconnections that the module will detect and publish. 🔥

This module depends on mod_pubsub and mod_disco.

Available options:

pubsub_host: undefined | string() — use this local PubSub host to advertise S2S connections. This must be a host local to this service handled by mod_pubsub. You only need this option if your configuration has more than one host in mod_pubsub's hosts option. The default value is the first host defined in the mod_pubsub hosts option. 🫶

Example:

modules:
  mod_pubsub_serverinfo:
    pubsub_host: custom.pubsub.domain.local

🔥 `mod_push` 🔥

This module implements the XMPP server's part of the push notification solution specified in XEP-0357: Push Notifications. It does not generate, like, APNS or FCM notifications directly — nope. 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-dependent backend services such as FCM or APNS. 💅

Available options:

cache_life_time: timeout() — same as the top-level cache_life_time option, but applied to this module only.
cache_missed: true | false — same as the top-level cache_missed option, but applied to this module only.
cache_size: pos_integer() | infinity — same as the top-level cache_size option, but applied to this module only.
db_type: mnesia | sql — same as the top-level default_db option, but applied to this module only.
include_body: true | false | Text — if this 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, and in that case the specified text will be included in place of the actual message body. This is useful to signal the app server whether the notification was triggered by a message with a body (as opposed to other types of traffic) without leaking the actual message contents. The default value is "New message". 🍓
include_sender: true | false — if this 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. 🙈
notify_on: messages | all — okay so this option was added in 23.10 ✨ If it’s set to messages, notifications are generated only for actual chat messages with a body text (or some encrypted payload). If it’s set to all, any kind of XMPP stanza will trigger a notification. If you’re unsure, it’s strongly recommended to stick to all, which is the default value. 💖
use_cache: true | false — same as the top-level use_cache option, but applied to this module only. 🫶

🏷️ API Tags: ../../developer/ejabberd-api/admin-tags.md#purge|purge

🛟 mod_push_keepalive

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. No cap.

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. ✨

📝 mod_register

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. If AccessName is none, then registering new accounts using In-Band Registration is disabled and the corresponding stream feature is not announced to clients. 🙈
access_from: AccessName — by default, ejabberd doesn’t allow the client to register new accounts from s2s or existing c2s sessions. You can change it by defining an 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. 🫶
allow_modules: all | [Module, ...] — note about this option: added in 21.12. 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 (basic.md#captcha|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. 🌸

Example:

modules:
  mod_register:
    welcome_message:
      subject: "Welcome!"
      body: |-
        Hi!
        Welcome to this XMPP server

🌐 mod_register_web

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 (basic.md#captcha|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 → listen-options.md#request_handlers|request_handlers.

There is no need to enable this module in modules, but it adds a link to the register page in WebAdmin menu. 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: {}

📒 mod_roster

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

🏷️ API Tags: ../../developer/ejabberd-api/admin-tags.md#roster|roster

🔁 mod_s2s_bidi

Note about this option: added in 24.10.

The module adds support for XEP-0288: Bidirectional Server-to-Server Connections that allows using single s2s connection to communicate in both directions. 🔥

The module has no options.

Example:

modules:
  mod_s2s_bidi: {}

🛡️ mod_s2s_dialback

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

🔐 mod_scram_upgrade

Note about this option: added in 24.10.

The module adds support for XEP-0480: SASL Upgrade Tasks that allows users to upgrade passwords to more secure representation. ✨

Available options:

offered_upgrades: list(sha256, sha512) — list with upgrade types that should be offered. 👑

Example:

modules:
  mod_scram_upgrade:
    offered_upgrades:
      - sha256
      - sha512

📤 mod_service_log

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

🫶 mod_shared_roster

Okay bestie so this module is the one that lets you make shared roster groups — aka groups of accounts that can see members from (other) groups right there in their rosters. Iconic, honestly. 💅

The big advantages (and yes, they're big): end users don't have to manually add every single user to their own rosters, and they cannot permanently delete users from the shared roster groups. Like, the group stays, no cap. 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 lets users keep / add their own contacts too, because it does not replace the standard roster. Instead, the shared roster contacts get merged into the relevant users' rosters at retrieval time, so the standard user rosters stay completely unmodified. Clean. ✨

Shared roster groups can be edited via the Web Admin, and also with some API commands called srg_, for example the srg_add API. Each group has a unique name and these parameters:

Label — used in the rosters where this group is displayed.
Description — of the group, which has no effect. (Decorative. A vibe. 💀)
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 another vhost can be identified with groupid@vhost.

Heads up bestie: this module depends on mod_roster. If it's not enabled, roster queries will return 503 errors. Not cute. 😭

Available options:

cache_life_time: timeout() — same as the top-level cache_life_time option, but applied to this module only.
cache_missed: true | false — same as the top-level cache_missed option, but applied to this module only.
cache_size: pos_integer() | infinity — same as the top-level cache_size option, but applied to this module only.
db_type: mnesia | sql — same as the top-level default_db option, but applied to this module only.
use_cache: true | false — same as the top-level use_cache option, but applied to this module only.

Examples ✨

Picture a computer club that wants all its members seeing each other in their rosters. To pull that off, they need to create a shared roster group kinda like 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've got a company with 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

🧚 mod_shared_roster_ldap

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. It's giving "the directory is the source of truth" and honestly? Obsessed. 💜

Note mod_shared_roster_ldap depends on mod_roster being enabled. Roster queries will return 503 errors if mod_roster is not enabled. Forewarned is forearmed, bestie. 🫶

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. Repetition is so not the vibe.

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.md#ldap-connection|LDAP Connection section for more information about them.

Check also the ldap.md#ldap-examples|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 ldap.md#filters|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 to.
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 ldap.md#control-parameters|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. (Yeah, this one's on you. 🙈)
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 ldap.md#filters|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 that maps a user id onto an XMPP jid. If you don't set it (and like, that's the default value of this option, so no pressure), the user jid gets built from the user id plus this module's host. ✨
ldap_useruid — the name of the attribute that holds the ID of a roster item. The value of this attribute in the roster item objects has to match the ID you pull from the ldap_memberattr attribute of a group object. It's retrieved from the results of the "User Filter". Defaults to cn. 💅
use_cache — same as the top-level use_cache option, but applied to this module only.

🦋 `mod_sic` 🦋

This module adds support for XEP-0279: Server IP Check. Basically this protocol lets a client discover its external IP address. iykyk 🌈

⚠️ Warning — the protocol extension is deferred and it 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. 😭 So like... maybe don't build your whole vibe on it?

The module has no options. periodt.

💜 `mod_sip` 💜

This module adds SIP proxy/registrar support for the corresponding virtual host. iconic behavior honestly 👑

📌 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 listen.md#ejabberd_sip listen module in the ejabberd Documentation. bestie please read the docs, I'm begging 🫶

Available options:

always_record_route: true | false — always insert "Record-Route" header into SIP messages. With this approach it's possible to bypass NATs/firewalls a bit more easily. The default value is true.
flow_timeout_tcp: timeout() — this option sets a keep-alive timer for SIP outbound TCP connections. The default value is 2 minutes.
flow_timeout_udp: timeout() — this option 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 a "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"). no skipping parts fr fr 💀

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

🍓 `mod_stats` 🍓

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 it seems like even a few clients that were supporting it are now abandoned. So using this module makes very little sense. 💀 like, the numbers are cute but nobody's asking for them anymore.

The module has no options.

🌸 `mod_stream_mgmt` 🌸

This module adds support for XEP-0198: Stream Management. This protocol allows active management of an XML stream between two XMPP entities, including features for stanza acknowledgments and stream resumption. this one's kind of a main character tbh 🔥

Available options:

ack_timeout: timeout() — a time to wait for stanza acknowledgments. Setting it to infinity effectively disables the timeout. The default value is 1 minute.
cache_life_time: timeout() — same as the 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 the 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 than 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 the 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.

🧚 `mod_stun_disco` 🧚

💫 Note about this option: added in 20.04.

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. honestly kind of a flex 🫶

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). 😭 classic restart betrayal.
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. no skipping, bestie 💅
port: 1..65535 — the port number the STUN/TURN service is listening on. default is 3478 for non-TLS services and 5349 for TLS services ✨
restricted: true | false — this one decides whether temporary credentials for accessing the service are offered. default is false for STUN/STUNS services and true for TURN/TURNS services 🔐
transport: tcp | udp — the transport protocol supported by the service. 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. 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

🌸 `mod_time` 🌸

okay so this module adds support for XEP-0202: Entity Time. literally all it does is report the server's system time 🕰️ iconic minimalism tbh.

the module has no options. not a single one. she's low-maintenance 💖

🦋 `mod_vcard` 🦋

this module lets end users store and retrieve their vCard, and retrieve other users' vCards, as defined in XEP-0054: vcard-temp. it also implements an uncomplicated Jabber User Directory based on the vCards of these users. and moreover (yes we're using moreover 💅) it enables the server to send its vCard when queried. main character module fr fr 👑

Available options:

allow_return_all: true | false — lets you specify if search operations with empty input fields should return all users who added some information to their vCard. default value is false. so no, you can't just yeet an empty search at it and get everyone's info by default 🙈
append_module_config: {VcardHost: Options} — note about this option: added in 26.07. it adds a few specific options to a certain upload host previously defined in the mod_vcard hosts option. right now only name can be defined here. this is similar to the toplevel append_host_config option, but in this case it's applied to this module's options. iykyk 🌈

Example:

modules:
  mod_vcard:
    hosts:
      - service1.@HOST@
      - service2.@HOST@
    name: "Service General"
    append_module_config:
      service1.localhost:
        name: "Service 1"
      service2.example.net:
        name: "Service 2"

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. she's retired, let her rest 💀
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. no cap, unless it's 31 results, then cap 🧢
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. 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. obsessed with how clean this is tbh 🫶

Example:

# This XML representation of vCard:
#
#   <vCard xmlns='vcard-temp'>
#     <FN>Conferences</FN>
#     <ADR>
#       <WORK/>
#       <STREET>Elm Street</STREET>
#     </ADR>
#   </vCard>
#
# is 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. 📝

Examples:

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. 🗺️

Examples:

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. 🧚

Examples:

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]}

the mnesia backend options, cont'd 💅

search_all_hosts: true | false — do we search across every virtual host or not? Default is true, bestie. That's the whole vibe.

mod_vcard_xupdate 🎀

okay so here's the tea ☕ — your client can stash an avatar inside the user vCard. The vCard-Based Avatars protocol (XEP-0153) gives clients a lil' method to tell contacts what the avatar hash value is. But simple or small clients may just… not implement that protocol 😭 bless them.

So if you enable this module, all the outgoing client presence stanzas get the avatar hash automatically, on behalf of the client. Meaning: the contacts receive presence stanzas with the Update Data described in XEP-0153, as if the client had inserted it itself ✨. And if the client already included such an element in the presence stanza? It gets replaced with the element generated by ejabberd. not me being the main character of your presence stanza 🙈.

But listen — by enabling this module, every vCard modification produces a hash recalculation, and every presence sent by a client produces hash retrieval plus a presence stanza rewrite 🔥. So yeah, enabling this module will introduce a computational overhead on servers with clients that change their presence frequently. 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. iykyk.

Available options:

cache_life_time: timeout() — same as the top-level cache_life_time option, but applied to this module only 🫶
cache_missed: true | false — same as the top-level cache_missed option, but applied to this module only 🫶
cache_size: pos_integer() | infinity — same as the top-level cache_size option, but applied to this module only 🫶
use_cache: true | false — same as the top-level use_cache option, but applied to this module only 🫶

mod_version ⭐

This module implements XEP-0092: Software Version. Consequently — and this is the slay part — 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. (yes bestie, by default we're spilling the OS tea 💀)

🌈 LISTENERS 🌈

This section describes listeners options of ejabberd 26.09.

TODO 🫠 (that's literally all it says — not me giving you a whole heading and then just TODO, iconic honestly 😭)

👑 AUTHOR 👑

ProcessOne. 💖

🦋 VERSION 🦋

This document describes the configuration file of ejabberd 26.09. Configuration options of other ejabberd versions may differ significantly — so like, don't come for me if you're on a different version, fr fr 🫶.

🍓 REPORTING BUGS 🍓

Report bugs to https://github.com/processone/ejabberd/issues — the devs wanna hear from you, bestie 🎀

✨ SEE ALSO ✨

Default configuration file: https://github.com/processone/ejabberd/blob/26.09/ejabberd.yml.example
Main site: https://ejabberd.im
Documentation: https://docs.ejabberd.im
Configuration Guide: https://docs.ejabberd.im/admin/configuration
Source code: https://github.com/processone/ejabberd

like, go read them, they ate 💅

🌸 COPYING 🌸

💖 and that's the whole page, bestie! this was EJABBERD.YML(5) from the ejabberd 26.09 gang, dated 09/29/2026 — go configure something iconic, mwah 🫶✨🎀

📦 where this page comes from

arch rolling: ejabberd 26.09.1-1 · GPL-2.0-or-later
nixos 26.05: ejabberd 26.09
nixpkgs unstable: ejabberd 26.09
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

EJABBERD.YML(5)

🎀 ejabberd.yml(5) — main configuration file for ejabberd 🎀

💖 NAME 💖

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

👑 TOP LEVEL OPTIONS 👑

🧩 MODULES 🧩

mod_adhoc

mod_adhoc_api

mod_admin_extra

Examples

mod_admin_update_sql

mod_announce

Available options

mod_antispam

Available options

Example

mod_auth_fast

🦋 mod_avatar

🚫 mod_block_strangers

🔒 mod_blocking

🌐 mod_bosh

🧩 mod_caps

📬 mod_carboncopy

💤 mod_client_state

⚙️ mod_configure

💬 mod_conversejs

🌸 mod_delegation 🌸

🦋 mod_disco 🦋

💀 mod_fail2ban 💀

🧚 mod_host_meta 🧚

🌸 mod_http_api

🎀 mod_http_fileserver

🦋 mod_http_upload

🌸 mod_http_upload_quota 🌸

🦋 mod_invites 🦋

🌈 mod_jidprep

🎀 mod_last

🦋 mod_legacy_auth

👑 mod_mam

💜 mod_matrix_gw

⭐ mod_metrics

🧚 mod_mix

🌸 mod_mix_pam

🦋 mod_mqtt 🦋

🔥 mod_mqtt_bridge 🔥

👑 mod_muc 👑

mod_muc_admin

mod_muc_log

mod_muc_rtbl

mod_multicast

mod_offline

🏓 mod_ping

🚨 mod_pres_counter

🕵️ mod_privacy

🔒 mod_private

👑 mod_privilege

📦 mod_providers

🦋 mod_proxy65

🌸 mod_pubsub

💖 Examples 💖

🦋 mod_pubsub_serverinfo 🦋

🔥 mod_push 🔥

🛟 mod_push_keepalive

📝 mod_register

🌐 mod_register_web

📒 mod_roster

🔁 mod_s2s_bidi

🛡️ mod_s2s_dialback

🔐 mod_scram_upgrade

📤 mod_service_log

🫶 mod_shared_roster

Examples ✨

🧚 mod_shared_roster_ldap

🦋 mod_sic 🦋

💜 mod_sip 💜

🍓 mod_stats 🍓

🌸 mod_stream_mgmt 🌸

🧚 mod_stun_disco 🧚

🌸 mod_time 🌸

🌸 `mod_http_api`

🎀 `mod_http_fileserver`

🦋 `mod_http_upload`

🌸 `mod_http_upload_quota` 🌸

🦋 `mod_invites` 🦋

🌈 `mod_jidprep`

🎀 `mod_last`

🦋 `mod_legacy_auth`

👑 `mod_mam`

💜 `mod_matrix_gw`

⭐ `mod_metrics`

🧚 `mod_mix`

🌸 `mod_mix_pam`

🦋 `mod_mqtt` 🦋

🔥 `mod_mqtt_bridge` 🔥

👑 `mod_muc` 👑

`mod_muc_admin`

`mod_muc_log`

`mod_muc_rtbl`

`mod_multicast`

`mod_offline`

🦋 `mod_proxy65`

🌸 `mod_pubsub`

🦋 `mod_pubsub_serverinfo` 🦋

🔥 `mod_push` 🔥

🦋 `mod_sic` 🦋

💜 `mod_sip` 💜

🍓 `mod_stats` 🍓

🌸 `mod_stream_mgmt` 🌸

🧚 `mod_stun_disco` 🧚

🌸 `mod_time` 🌸

🦋 `mod_vcard` 🦋

🌟 Available options for `ldap` backend 🌟