Skip to content

# Modules Options

Please note

This section describes modules options of ejabberd 26.03. If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive.

The modules that changed in this version are marked with 🟠.

## mod_adhoc

ad-hoc command

Command that can be executed by an XMPP client using XEP-0050.

This module implements XEP-0050: Ad-Hoc Commands. It’s an auxiliary module and is only needed by some of the other modules.

Available options:

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

## mod_adhoc_api

added in 25.03

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

Available options:

- default_version: `integer() | string()`
  What API version to use. If setting an ejabberd version, it will use the latest API version that was available in that c2s ejabberd version. For example, setting `"24.06"` in this option implies `2`. The default value is the latest version.

Example:

    acl:
      admin:
        user: jan@localhost

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

    modules:
      mod_adhoc_api:
        default_version: 2

## mod_admin_extra

This module provides additional administrative commands.

Details for some commands:

ban_account API: This command kicks all the connected sessions of the account from the server. It also changes their password to a randomly generated one, so they can’t login anymore unless a server administrator changes their password again. It is possible to define the reason of the ban. The new password also includes the reason and the date and time of the ban. See an example below.

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

srg_create API: If you want to put a group Name with blank spaces, use the characters `"`' and `'"` to define when the Name starts and ends. See an example below.

The module has no options.

Examples:

With this configuration, vCards can only be modified with mod_admin_extra commands:

    acl:
      adminextraresource:
        - resource: "modadminextraf8x,31ad"
    access_rules:
      vcard_set:
        - allow: adminextraresource
    modules:
      mod_admin_extra: {}
      mod_vcard:
        access_set: vcard_set

Content of roster file for push_roster API:

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

With this call, the sessions of the local account which JID is `boby@example.org` will be kicked, and its password will be set to something like `BANNED_ACCOUNT—20080425T21:45:07—2176635—Spammed_rooms`

    ejabberdctl vhost example.org ban_account boby "Spammed rooms"

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

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

API Tags: accounts, erlang, last, private, purge, roster, session, shared_roster_group, stanza, statistics, vcard

## mod_admin_update_sql

This module can be used to convert your existing SQL database from the singlehost to the multihost schema. Check the section Singlehost or Multihost for details. Please note that only MS SQL, MySQL, and PostgreSQL are supported. When the module is loaded use update_sql API.

The module has no options.

API Tags: sql

## mod_announce

This module enables configured users to broadcast announcements and to set the message of the day (MOTD). Configured users can perform these actions with an XMPP client either using Ad-Hoc Commands or sending messages to specific JIDs. Equivalent API commands are also available.

Note

This module can be resource intensive on large deployments as it may broadcast a lot of messages. This module should be disabled for instances of ejabberd with hundreds of thousands users.

To send announcements using XEP-0050: Ad-Hoc Commands, this module requires mod_adhoc (to execute the commands), and recommends mod_disco (to discover the commands).

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

- `example.org/announce/all`: Send the message to all registered users in that vhost. If the user is online and connected to several resources, only the resource with the highest priority will receive the message. If the registered user is not connected, the message is stored offline in assumption that offline storage (see mod_offline) is enabled.

- `example.org/announce/online`: Send the message to all connected users. If the user is online and connected to several resources, all resources will receive the message.

- `example.org/announce/motd`: Set the message of the day (MOTD) that is sent to users when they login. Also sends the message to all connected users (similar to `announce/online`).

- `example.org/announce/motd/update`: Set the message of the day (MOTD) that is sent to users when they login. This does not send the message to any currently connected user.

- `example.org/announce/motd/delete`: Remove the existing message of the day (MOTD) by sending a message to this JID.

There are similar destination JIDs to apply to all virtual hosts in ejabberd:

- `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 option specifies who is allowed to send announcements and to set the message of the day. The default value is `none` (i.e. nobody is able to send such messages).

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

API Tags: announce

## mod_antispam

added in 25.07

Filter spam messages and subscription requests received from remote servers based on Real-Time Block Lists (RTBL), lists of known spammer JIDs and/or URLs mentioned in spam messages. Traffic classified as spam is rejected with an error (and an [info] message is logged) unless the sender is subscribed to the recipient’s presence.

Available options:

- access_spam: `Access`
  Access rule that controls what accounts may receive spam messages. If the rule returns `allow` for a given recipient, spam messages aren’t rejected for that recipient. The default value is `none`, which means that all recipients are subject to spam filtering verification.

- cache_size: `pos_integer()`
  Maximum number of JIDs that will be cached due to sending spam URLs. If that limit is exceeded, the least recently used entries are removed from the cache. Setting this option to `0` disables the caching feature. Note that separate caches are used for each virtual host, and that the caches aren’t distributed across cluster nodes. The default value is `10000`.

- rtbl_services: `[Service]`
  Query a RTBL service to get domains to block, as provided by xmppbl.org. Please note right now this option only supports one service in that list. For blocking spam and abuse on MUC channels, please use mod_muc_rtbl for now. If only the host is provided, the default node names will be assumed. If the node name is different than `spam_source_domains`, you can setup the custom node name with the option `spam_source_domains_node`. The default value is an empty list of services.

  Example:

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

- spam_domains_file: `none | Path`
  Path to a plain text file containing a list of known spam domains, one domain per line. Messages and subscription requests sent from one of the listed domains are classified as spam if sender is not in recipient’s roster. This list of domains gets merged with the one retrieved by an RTBL host if any given. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is `none`.

- spam_dump_file: `false | true | Path`
  Path to the file to store blocked messages. Use an absolute path, or the `@LOG_PATH@` predefined keyword to store logs in the same place that the other ejabberd log files. If set to `false`, it doesn’t dump stanzas, which is the default. If set to `true`, it stores in `"@LOG_PATH@/spam_dump_@HOST@.log"`.

- spam_jids_file: `none | Path`
  Path to a plain text file containing a list of known spammer JIDs, one JID per line. Messages and subscription requests sent from one of the listed JIDs are classified as spam. Messages containing at least one of the listed JIDsare classified as spam as well. Furthermore, the sender’s JID will be cached, so that future traffic originating from that JID will also be classified as spam. Use an absolute path, or the `@CONFIG_PATH@` predefined keyword if the file is available in the configuration directory. The default value is `none`.

- spam_urls_file: `none | Path`
  Path to a plain text file containing a list of URLs known to be mentioned in spam message bodies. Messages containing at least one of the listed URLs are classified as spam. Furthermore, the sender’s JID will be cached, so that future traffic originating from that JID will be classified as spam as well. Use an absolute path, or the `@CONFIG_PATH@` predefined keyword if the file is available in the configuration directory. The default value is `none`.

- whitelist_domains_file: `none | Path`
  Path to a file containing a list of domains to whitelist from being blocked, one per line. If either it is in `spam_domains_file` or more realistically in a domain sent by a RTBL host (see option `rtbl_services`) then this domain will be ignored and stanzas from there won’t be blocked. Use an absolute path, or the @CONFIG_PATH@ predefined keyword if the file is available in the configuration directory. The default value is `none`.

Example:

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

API Tags: spam

## mod_auth_fast

added in 24.12

The module adds support for XEP-0484: Fast Authentication Streamlining Tokens that allows users to authenticate using self-managed tokens.

Available options:

- db_type: `mnesia`
  Same as top-level default_db option, but applied to this module only.

- token_lifetime: `timeout()`
  Time that tokens will be kept, measured from it’s creation time. Default value set to 30 days

- token_refresh_age: `timeout()`
  This time determines age of token, that qualifies for automatic refresh. Default value set to 1 day

Example:

    modules:
      mod_auth_fast:
        token_lifetime: 14days

## mod_avatar

The purpose of the module is to cope with legacy and modern XMPP clients posting avatars. The process is described in XEP-0398: User Avatar to vCard-Based Avatars Conversion.

Also, the module supports conversion between avatar image formats on the fly.

The module depends on mod_vcard, mod_vcard_xupdate and mod_pubsub.

Available options:

- convert: `{From: To}`
  Defines image conversion rules: the format in `From` will be converted to format in `To`. The value of `From` can also be `default`, which is match-all rule. NOTE: the list of supported formats is detected at compile time depending on the image libraries installed in the system.

  Example:

      convert:
        webp: jpg
        default: png

- rate_limit: `Number`
  Limit any given JID by the number of avatars it is able to convert per minute. This is to protect the server from image conversion DoS. The default value is `10`.

## mod_block_strangers

This module blocks and logs any messages coming from an unknown entity. If a writing entity is not in your roster, you can let this module drop and/or log the message. By default you’ll just not receive message from that entity. Enable this module if you want to drop SPAM messages.

Available options:

- access: `AccessName`
  The option is supposed to be used when `allow_local_users` and `allow_transports* are not enough. It’s an Access Rule where *deny` means the stanza will be rejected; there’s an exception if option `captcha` is configured. And `allow` means the sender is whitelisted and the stanza will pass through. The default value is `none`, which means nothing is whitelisted.

- allow_local_users: `true | false`
  This option specifies if strangers from the same local host should be accepted or not. The default value is `true`.

- allow_transports: `true | false`
  If set to `true` and some server’s JID is in user’s roster, then messages from any user of this server are accepted even if no subscription present. The default value is `true`.

- captcha: `true | false`
  Whether to generate CAPTCHA challenges in response to incoming presence subscription requests from strangers. See also section CAPTCHA of the Configuration Guide. The default value is `false`.

- drop: `true | false`
  This option specifies if strangers messages should be dropped or not. The default value is `true`.

- log: `true | false`
  This option specifies if strangers' messages should be logged (as info message) in ejabberd.log. The default value is `false`.

## mod_blocking

The module implements XEP-0191: Blocking Command.

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

The module has no options.

## mod_bosh

This module implements XMPP over BOSH as defined in XEP-0124 and XEP-0206. BOSH stands for Bidirectional-streams Over Synchronous HTTP. It makes it possible to simulate long lived connections required by XMPP over the HTTP protocol. In practice, this module makes it possible to use XMPP in a browser without WebSocket support and more generally to have a way to use XMPP while having to get through an HTTP proxy.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- json: `true | false`
  This option has no effect.

- max_concat: `pos_integer() | infinity`
  This option limits the number of stanzas that the server will send in a single bosh request. The default value is `unlimited`.

- max_inactivity: `timeout()`
  The option defines the maximum inactivity period. The default value is `30` seconds.

- max_pause: `pos_integer()`
  Indicate the maximum length of a temporary session pause (in seconds) that a client can request. The default value is `120`.

- prebind: `true | false`
  If enabled, the client can create the session without going through authentication. Basically, it creates a new session with anonymous authentication. The default value is `false`.

- queue_type: `ram | file`
  Same as top-level queue_type option, but applied to this module only.

- ram_db_type: `mnesia | sql | redis`
  Same as top-level default_ram_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

Example:

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

    modules:
      mod_bosh: {}

## mod_caps

This module implements XEP-0115: Entity Capabilities. The main purpose of the module is to provide PEP functionality (see mod_pubsub).

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

## mod_carboncopy

The module implements XEP-0280: Message Carbons. The module broadcasts messages on all connected user resources (devices).

The module has no options.

## mod_client_state

This module allows for queueing certain types of stanzas when a client indicates that the user is not actively using the client right now (see XEP-0352: Client State Indication). This can save bandwidth and resources.

A stanza is dropped from the queue if it’s effectively obsoleted by a new one (e.g., a new presence stanza would replace an old one from the same client). The queue is flushed if a stanza arrives that won’t be queued, or if the queue size reaches a certain limit (currently 100 stanzas), or if the client becomes active again.

Available options:

- queue_chat_states: `true | false`
  Queue "standalone" chat state notifications (as defined in XEP-0085: Chat State Notifications) while a client indicates inactivity. The default value is `true`.

- queue_pep: `true | false`
  Queue PEP notifications while a client is inactive. When the queue is flushed, only the most recent notification of a given PEP node is delivered. The default value is `true`.

- queue_presence: `true | false`
  While a client is inactive, queue presence stanzas that indicate (un)availability. The default value is `true`.

## mod_configure

improved in 25.10

The 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 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:

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

Available options:

- access: `AccessName`
  added in 25.03 This option defines which access rule will be used to control who is allowed to access the features provided by this module. The default value is `configure`.

Example:

    acl:
      admin:
        user: sun@localhost

    access_rules:
      configure:
        allow: admin

    modules:
      mod_configure:
        access: configure

## mod_conversejs

improved in 25.07

This module serves a simple page for the Converse XMPP web browser client.

To use this module, in addition to adding it to the `modules` section, you must also enable it in `listen` → `ejabberd_http` → request_handlers.

Make sure either mod_bosh or ejabberd_http_ws are enabled in at least one `request_handlers`.

When `conversejs_css` and `conversejs_script` are `auto`, by default they point to the public Converse client.

When this module is enabled in `modules`, it adds automatically a requesthandler and link in WebAdmin. .

This module is available since ejabberd 21.12.

Available options:

- bosh_service_url: `auto | BoshURL`
  BOSH service URL to which Converse can connect to. The keyword @HOST@ is replaced with the real virtual host name. If set to `auto`, it will build the URL of the first configured BOSH request handler. The default value is `auto`.

- conversejs_css: `auto | URL`
  Converse CSS URL. The keyword `@HOST@` is replaced with the hostname. The default value is `auto`.

- conversejs_options: `{Name: Value}`
  added in 22.05 Specify additional options to be passed to Converse. See Converse configuration. Only boolean, integer and string values are supported; lists are not supported.

- conversejs_plugins: `[Filename]`
  List of additional local files to include as scripts in the homepage. Please make sure those files are available in the path specified in `conversejs_resources` option, in subdirectory `plugins/`. If using the public Converse client, then `"libsignal"` gets replaced with the URL of the public library. The default value is `[]`.

- conversejs_resources: `Path`
  added in 22.05 Local path to the Converse files. If not set, the public Converse client will be used instead.

- conversejs_script: `auto | URL`
  Converse main script URL. The keyword `@HOST@` is replaced with the hostname. The default value is `auto`.

- default_domain: `Domain`
  Specify a domain to act as the default for user JIDs. The keyword `@HOST@` is replaced with the hostname. The default value is `@HOST@`.

- websocket_url: `auto | WebSocketURL`
  A WebSocket URL to which Converse can connect to. The `@HOST@` keyword is replaced with the real virtual host name. If set to `auto`, it will build the URL of the first configured WebSocket request handler. The default value is `auto`.

Examples:

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

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

    modules:
      mod_bosh: {}
      mod_conversejs:
        conversejs_plugins: ["libsignal"]
        websocket_url: "ws://@HOST@:5280/websocket"

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

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

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

Configure some additional options for Converse

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

## mod_delegation

This module is an implementation of XEP-0355: Namespace Delegation. Only admin mode has been implemented by now. Namespace delegation allows external services to handle IQ using specific namespace. This may be applied for external PEP service.

Warning

Security issue: Namespace delegation gives components access to sensitive data, so permission should be granted carefully, only if you trust the component.

Note

This module is complementary to mod_privilege but can also be used separately.

Available options:

- namespaces: `{Namespace: Options}`
  If you want to delegate namespaces to a component, specify them in this option, and associate them to an access rule. The `Options` are:

  - access: `AccessName`
    The option defines which components are allowed for namespace delegation. The default value is `none`.

  - filtering: `Attributes`
    The list of attributes. Currently not used.

Examples:

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

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

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

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

## mod_disco

This module adds support for XEP-0030: Service Discovery. With this module enabled, services on your server can be discovered by XMPP clients.

Available options:

- extra_domains: `[Domain, ...]`
  With this option, you can specify a list of extra domains that are added to the Service Discovery item list. The default value is an empty list.

- name: `Name`
  A name of the server in the Service Discovery. This will only be displayed by special XMPP clients. The default value is `ejabberd`.

- server_info: `[Info, ...]`
  Specify additional information about the server, as described in XEP-0157: Contact Addresses for XMPP Services. Every `Info` element in the list is constructed from the following options:

  - modules: `all | [Module, ...]`
    The value can be the keyword `all`, in which case the information is reported in all the services, or a list of ejabberd modules, in which case the information is only specified for the services provided by those modules.

  - name: `Name`
    The field `var` name that will be defined. See XEP-0157 for some standardized names.

  - urls: `[URI, ...]`
    A list of contact URIs, such as HTTP URLs, XMPP URIs and so on.

  Example:

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

## mod_fail2ban

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

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

Warning

You should not use this module behind a proxy or load balancer. ejabberd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer. You can lock all your user base out of ejabberd when using this module behind a proxy.

Available options:

- access: `AccessName`
  Specify an access rule for whitelisting IP addresses or networks. If the rule returns `allow` for a given IP address, that address will never be banned. The `AccessName` should be of type `ip`. The default value is `none`.

- c2s_auth_ban_lifetime: `timeout()`
  The lifetime of the IP ban caused by too many C2S authentication failures. The default value is `1` hour.

- c2s_max_auth_failures: `Number`
  The number of C2S authentication failures to trigger the IP ban. The default value is `20`.

API Tags: accounts

## mod_host_meta

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` → request_handlers.

Notice it only works if ejabberd_http has tls enabled.

Available options:

- bosh_service_url: `undefined | auto | BoshURL`
  BOSH service URL to announce. The keyword `@HOST@` is replaced with the real virtual host name. If set to `auto`, it will build the URL of the first configured BOSH request handler. The default value is `auto`.

- websocket_url: `undefined | auto | WebSocketURL`
  WebSocket URL to announce. The keyword `@HOST@` is replaced with the real virtual host name. If set to `auto`, it will build the URL of the first configured WebSocket request handler. The default value is `auto`.

Example:

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

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

## mod_http_api

This module provides a ReST interface to call ejabberd API commands using JSON data.

To use this module, in addition to adding it to the `modules` section, you must also enable it in `listen` → `ejabberd_http` → request_handlers.

To use a specific API version N, when defining the URL path in the request_handlers, add a vN. For example: `/api/v2: mod_http_api`.

To run a command, send a POST request to the corresponding URL: `http://localhost:5280/api/COMMAND-NAME`

Available options:

- default_version: `integer() | string()`
  added in 24.12 What API version to use when none is specified in the URL path. If setting an ejabberd version, it will use the latest API version that was available in that ejabberd version. For example, setting `"24.06"` in this option implies `2`. The default value is the latest version.

Example:

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

    modules:
      mod_http_api:
        default_version: 2

## mod_http_fileserver

improved `docroot` in 26.01

This simple module serves files from the local disk over HTTP.

Available options:

- accesslog: `Path`
  File to log accesses using an Apache-like format. No log will be recorded if this option is not specified.

- content_types: `{Extension: Type}`
  Specify mappings of extension to content type. There are several content types already defined. With this option you can add new definitions or modify existing ones. The default values are:

  Example:

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

- custom_headers: `{Name: Value}`
  Indicate custom HTTP headers to be included in all responses. There are no custom headers by default.

- default_content_type: `Type`
  Specify the content type to use for unknown extensions. The default value is `application/octet-stream`.

- directory_indices: `[Index, ...]`
  Indicate one or more directory index files, similarly to Apache’s `DirectoryIndex` variable. When an HTTP request hits a directory instead of a regular file, those directory indices are looked in order, and the first one found is returned. The default value is an empty list.

- docroot: `PathDir | {PathURL, PathDir}`
  improved in 26.01 Directory to serve the files from, or a map with several URL path (as specified in request_handlers) and their corresponding directory. This is a mandatory option.

  Example:

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

- must_authenticate_with: `[{Username, Hostname}, ...]`
  List of accounts that are allowed to use this service. Default value: `[]`.

Examples:

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

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

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

## mod_http_upload

added `content_types` in 26.01

This module allows for requesting permissions to upload a file via HTTP as described in XEP-0363: HTTP File Upload. If the request is accepted, the client receives a URL for uploading the file and another URL from which that file can later be downloaded.

In order to use this module, it must be enabled in `listen` → `ejabberd_http` → request_handlers.

Available options:

- access: `AccessName`
  This option defines the access rule to limit who is permitted to use the HTTP upload service. The default value is `local`. If no access rule of that name exists, no user will be allowed to use the service.

- content_types: `{Extension: Type}`
  added in 26.01 Specify mappings of extension to content type, similarly to the option `content_types` of mod_http_fileserver.

- custom_headers: `{Name: Value}`
  This option specifies additional header fields to be included in all HTTP responses. By default no custom headers are included.

- dir_mode: `Permission`
  This option defines the permission bits of the `docroot` directory and any directories created during file uploads. The bits are specified as an octal number (see the `chmod(1)` manual page) within double quotes. For example: `"0755"`. The default is undefined, which means no explicit permissions will be set.

- docroot: `Path`
  Uploaded files are stored below the directory specified (as an absolute path) with this option. The keyword `@HOME@` is replaced with the home directory of the user running ejabberd, and the keyword `@HOST@` with the virtual host name. The default value is `"@HOME@/upload"`.

- external_secret: `Text`
  This option makes it possible to offload all HTTP Upload processing to a separate HTTP server. Both ejabberd and the HTTP server should share this secret and behave exactly as described at Prosody’s mod_http_upload_external: Implementation. There is no default value.

- file_mode: `Permission`
  This option defines the permission bits of uploaded files. The bits are specified as an octal number (see the `chmod(1)` manual page) within double quotes. For example: `"0644"`. The default is undefined, which means no explicit permissions will be set.

- get_url: `URL`
  This option specifies the initial part of the GET URLs used for downloading the files. The default value is `undefined`. When this option is `undefined`, this option is set to the same value as `put_url`. The keyword `@HOST@` is replaced with the virtual host name. NOTE: if GET requests are handled by this module, the `get_url` must match the `put_url`. Setting it to a different value only makes sense if an external web server or mod_http_fileserver is used to serve the uploaded files.

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix `"upload."`. The keyword `@HOST@` is replaced with the real virtual host name.

- jid_in_url: `node | sha1`
  When this option is set to `node`, the node identifier of the user’s JID (i.e., the user name) is included in the GET and PUT URLs generated by `mod_http_upload`. Otherwise, a SHA-1 hash of the user’s bare JID is included instead. The default value is `sha1`.

- max_size: `Size`
  This option limits the acceptable file size. Either a number of bytes (larger than zero) or `infinity` must be specified. The default value is `104857600`.

- name: `Name`
  A name of the service in the Service Discovery. The default value is `"HTTP File Upload"`. Please note this will only be displayed by some XMPP clients.

- put_url: `URL`
  This option specifies the initial part of the PUT URLs used for file uploads. The keyword `@HOST@` is replaced with the virtual host name. And `@HOST_URL_ENCODE@` is replaced with the host name encoded for URL, useful when your virtual hosts contain non-latin characters. NOTE: different virtual hosts cannot use the same PUT URL. The default value is `"https://@HOST@:5443/upload"`.

- rm_on_unregister: `true | false`
  This option specifies whether files uploaded by a user should be removed when that user is unregistered. The default value is `true`.

- secret_length: `Length`
  This option defines the length of the random string included in the GET and PUT URLs generated by `mod_http_upload`. The minimum length is `8` characters, but it is recommended to choose a larger value. The default value is `40`.

- service_url
  Deprecated.

- thumbnail: `true | false`
  This option specifies whether ejabberd should create thumbnails of uploaded images. If a thumbnail is created, a <thumbnail/> element that contains the download <uri/> and some metadata is returned with the PUT response. The default value is `false`.

- vcard: `vCard`
  A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery. The value of `vCard` is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward.

  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.

This module depends on mod_http_upload.

Available options:

- access_hard_quota: `AccessName`
  This option defines which access rule is used to specify the "hard quota" for the matching JIDs. That rule must yield a positive number for any JID that is supposed to have a quota limit. This is the number of megabytes a corresponding user may upload. When this threshold is exceeded, ejabberd deletes the oldest files uploaded by that user until their disk usage equals or falls below the specified soft quota (see also option `access_soft_quota`). The default value is `hard_upload_quota`.

- access_soft_quota: `AccessName`
  This option defines which access rule is used to specify the "soft quota" for the matching JIDs. That rule must yield a positive number of megabytes for any JID that is supposed to have a quota limit. See the description of the `access_hard_quota` option for details. The default value is `soft_upload_quota`.

- max_days: `Days`
  If a number larger than zero is specified, any files (and directories) older than this number of days are removed from the subdirectories of the `docroot` directory, once per day. The default value is `infinity`.

Examples:

Notice it’s not necessary to specify the `access_hard_quota` and `access_soft_quota` options in order to use the quota feature. You can stick to the default names and just specify access rules such as those in this example:

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

    modules:
      mod_http_upload: {}
      mod_http_upload_quota:
        max_days: 100

## mod_invites 🟠

improved in 26.03

Allow User Invitation and Account Creation to create out-of-band links to onboard others onto the XMPP network and establish a mutual subscription. This implements XEP-0379: Pre-Authenticated Roster Subscription, XEP-0401: Ad-hoc Account Invitation Generation, and XEP-0445: Pre-Authenticated In-Band Registration.

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

The receiving user should have installed a client that supports those invitations. Since this has proven to be a common obstacle for easy adoption, this module comes with an optional landing page parameter, that can either be some external service like an installation of easy-xmpp-invitation, a third-party service like JoinJabber or for convenience a built-in service. This landing page will then guide the recipient with setting up a client and creating an account if required.

In order to use the included landing page feature, you have to set `landing_page` to either `auto` or an URL template like `https://{{ host }}/invites/{{ invite.token }}` if your server setup includes a so called reverse proxy.

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

Available options:

- access_create_account: `Access Rule Name`
  This is the name of an access rule that specifies who is allowed to create invites of `create account`. The default value is `none`, i.e. nobody is able to create such invites. Furthermore it applies to roster invites and allows to do in-band registration (IBR) if the sending user is allowed by this rule. Users from the `admin` ACL are always allowed to create those invites.

  Example:

      mod_invites:
        access_create_account: local

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- landing_page: `none | auto | LandingPageURLTemplate`
  Whether or not to use a landing page for the invites that are being created. If using a template URL this can be either be external or internal. Template variables include `host`, `invite.token` and `invite.uri`, there are also filters defined, most notably `strip_protocol`. Here’s an example: `http://{{ host }}:8080/easy-xmpp-invites/#{{ invite.uri|strip_protocol }}`. For convenience you can choose `auto` here and the `ejabberd_http` handler for `mod_invites` will be used to construct the landing page URL. Default is `none`.

- max_invites: `pos_integer() | infinity`
  Maximum number of `create account` invites that can be created by an individual user. Users that match the `admin` ACL are exempt from this limitation. Furthermore it restricts the use of `roster invites` for account creation. Default is `infinity`.

- site_name: `Site Name`
  A human readable name for your site. E.g. `"My Beautiful Laundrette"`. Used in landing page templates.

- templates_dir: `Path`
  The directory containing templates and static files used for landing page and web registration form. Only needs to be set if you want to ship your own set of templates or list of recommended apps.

- token_expire_seconds: `pos_integer()`
  Number of seconds until token expires. Default value is `432000` (that is five days: `5 * 24 * 60 * 60`)

- *webchat_url 🟠`*:`none | auto | Webchat URL
  added in 26.03 URL to a webchat client. Upon manual registration through web-form this will be recommended in order to get started. If `auto` is chosen, we pick the `mod_conversejs` from the listeners section. Default is `auto`.

Examples:

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

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

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

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

    access_rules:
      register:
        allow: admin

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

If you want all your users to be able to send `create account` invites, you would configure your server like this instead. Note that the names of the access rules are just examples and you’re free to change them.

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

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

API Tags: accounts, purge

## mod_jidprep

This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format. This might be useful for clients in certain constrained environments, or for testing purposes.

Available options:

- access: `AccessName`
  This option defines which access rule will be used to control who is allowed to use this service. The default value is `local`.

## mod_last

This module adds support for XEP-0012: Last Activity. It can be used to discover when a disconnected user last accessed the server, to know when a connected user was last active on the server, or to query the uptime of the ejabberd server.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

## mod_legacy_auth

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

Note

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

The module has no options.

## mod_mam

This module implements XEP-0313: Message Archive Management and XEP-0441: Message Archive Management Preferences. Compatible XMPP clients can use it to store their chat history on the server.

Note

Mnesia backend for mod_mam is not recommended: it’s limited to 2GB and often gets corrupted when reaching this limit. SQL backend is recommended. Namely, for small servers SQLite is a preferred choice because it’s very easy to configure.

Available options:

- access_preferences: `AccessName`
  This access rule defines who is allowed to modify the MAM preferences. The default value is `all`.

- archive_muc_as_mucsub: `true | false`
  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: mam, purge

## mod_matrix_gw

improved in 25.08

Matrix gateway. Supports room versions 9, 10 and 11 since ejabberd 25.03; room versions 4 and higher since ejabberd 25.07; room version 12 (hydra rooms) since ejabberd 25.08. Erlang/OTP 25 or higher is required to use this module. This module is available since ejabberd 24.02.

Available options:

- host: `Host`
  This option defines the Jabber IDs of the service. If the `host` option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix `"matrix."`. The keyword `@HOST@` is replaced with the real virtual host name.

- key: `string()`
  Value of the matrix signing key, in base64.

- key_name: `string()`
  Name of the matrix signing key.

- leave_timeout: `integer()`
  Delay in seconds between a user leaving a MUC room and sending `leave` Matrix event.

- matrix_domain: `Domain`
  Specify a domain in the Matrix federation. The keyword `@HOST@` is replaced with the hostname. The default value is `@HOST@`.

- matrix_id_as_jid: `true | false`
  If set to `true`, all packets failing to be delivered via an XMPP server-to-server connection will then be routed to the Matrix gateway by translating a Jabber ID `user@matrixdomain.tld` to a Matrix user identifier `@user:matrixdomain.tld`. When set to `false`, messages must be explicitly sent to the matrix gateway service Jabber ID to be routed to a remote Matrix server. In this case, to send a message to Matrix user `@user:matrixdomain.tld`, the client must send a message to the JID `user%<matrixdomain.tld@matrix.myxmppdomain>.tld`, where `matrix.myxmppdomain.tld` is the JID of the gateway service as set by the `host` option. The default is `false`.

- notary_servers: `[Server, ...]`
  A list of notary servers.

Example:

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

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

## mod_metrics

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

- sm_register_connection

- sm_remove_connection

- user_send_packet

- user_receive_packet

- s2s_send_packet

- s2s_receive_packet

- register_user

- remove_user

- offline_message

When enabled, every call to these hooks triggers a counter event to be sent to the external backend.

Available options:

- ip: `IPv4Address`
  IPv4 address where the backend is located. The default value is `127.0.0.1`.

- port: `Port`
  An internet port number at which the backend is listening for incoming connections/packets. The default value is `11111`.

## mod_mix

added in 16.03 and improved in 19.02

This module is an experimental implementation of XEP-0369: Mediated Information eXchange (MIX). It’s asserted that the MIX protocol is going to replace the MUC protocol in the future (see mod_muc).

To learn more about how to use that feature, you can refer to our tutorial: Getting started with MIX

The module depends on mod_mam.

Available options:

- access_create: `AccessName`
  An access rule to control MIX channels creations. The default value is `all`.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix `"mix."`. The keyword `@HOST@` is replaced with the real virtual host name.

- name: `Name`
  A name of the service in the Service Discovery. This will only be displayed by special XMPP clients. The default value is `Channels`.

## mod_mix_pam

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

Note

mod_mix is not required for this module to work, however, without `mod_mix_pam` the MIX functionality of your local XMPP clients will be impaired.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

## mod_mqtt

This module adds support for the MQTT protocol version `3.1.1` and `5.0`. Remember to configure `mod_mqtt` in `modules` and `listen` sections.

Available options:

- access_publish: `{TopicFilter: AccessName}`
  Access rules to restrict access to topics for publishers. By default there are no restrictions.

- access_subscribe: `{TopicFilter: AccessName}`
  Access rules to restrict access to topics for subscribers. By default there are no restrictions.

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- match_retained_limit: `pos_integer() | infinity`
  The option limits the number of retained messages returned to a client when it subscribes to some topic filter. The default value is `1000`.

- max_queue: `Size`
  Maximum queue size for outgoing packets. The default value is `5000`.

- max_topic_aliases: `0..65535`
  The maximum number of aliases a client is able to associate with the topics. The default value is `100`.

- max_topic_depth: `Depth`
  The maximum topic depth, i.e. the number of slashes (`/`) in the topic. The default value is `8`.

- queue_type: `ram | file`
  Same as top-level queue_type option, but applied to this module only.

- ram_db_type: `mnesia`
  Same as top-level default_ram_db option, but applied to this module only.

- session_expiry: `timeout()`
  The option specifies how long to wait for an MQTT session resumption. When `0` is set, the session gets destroyed when the underlying client connection is closed. The default value is `5` minutes.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

## mod_mqtt_bridge

This module adds ability to synchronize local MQTT topics with data on remote servers It can update topics on remote servers when local user updates local topic, or can subscribe for changes on remote server, and update local copy when remote data is updated. It is available since ejabberd 23.01.

Available options:

- replication_user: `JID`
  Identifier of a user that will be assigned as owner of local changes.

- servers: `{ServerUrl: {Key: Value}}`
  Declaration of data to share for each ServerUrl. Server URLs can use schemas: `mqtt`, `mqtts` (mqtt with tls), `mqtt5`, `mqtt5s` (both to trigger v5 protocol), `ws`, `wss`, `ws5`, `wss5`. Keys must be:

  - authentication: `{AuthKey: AuthValue}`
    List of authentication information, where AuthKey can be: `username` and `password` fields, or `certfile` pointing to client certificate. Certificate authentication can be used only with mqtts, mqtt5s, wss, wss5.

  - publish: `{LocalTopic: RemoteTopic}`
    Either publish or subscribe must be set, or both.

  - subscribe: `{RemoteTopic: LocalTopic}`
    Either publish or subscribe must be set, or both.

Example:

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

## mod_muc

incorporated `mod_muc_occupantid` in 26.02

This module provides support for Multi-User Chat (MUC). Users can discover existing rooms, join or create them. Occupants of a room can chat in public or have private chats.

Protocols implemented in this module:

- 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 allows any Jabber ID to register a nickname, so nobody else can use that nickname in any room in the MUC service. To register a nickname, open the Service Discovery in your XMPP client and register in the MUC service.

It is also possible to register a nickname in a room, so nobody else can use that nickname in that room. If a nick is registered in the MUC service, that nick cannot be registered in any room, and vice versa: a nick that is registered in a room cannot be registered at the MUC service.

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

Available options:

- access: `AccessName`
  You can specify who is allowed to use the Multi-User Chat service. By default everyone is allowed to use it.

- access_admin: `AccessName`
  This option specifies who is allowed to administrate the Multi-User Chat service. The default value is `none`, which means that only the room creator can administer their room. The administrators can send a normal message to the service JID, and it will be shown in all active rooms as a service message. The administrators can send a groupchat message to the JID of an active room, and the message will be shown in the room as a service message.

- access_create: `AccessName`
  To configure who is allowed to create new rooms at the Multi-User Chat service, this option can be used. The default value is `all`, which means everyone is allowed to create rooms.

- access_mam: `AccessName`
  To configure who is allowed to modify the `mam` room option. The default value is `all`, which means everyone is allowed to modify that option.

- access_persistent: `AccessName`
  To configure who is allowed to modify the `persistent` room option. The default value is `all`, which means everyone is allowed to modify that option.

- access_register: `AccessName`
  improved in 23.10 This option specifies who is allowed to register nickname within the Multi-User Chat service and rooms. The default is `all` for backward compatibility, which means that any user is allowed to register any free nick in the MUC service and in the rooms.

- cleanup_affiliations_on_start: `true | false`
  added in 22.05 Remove affiliations for non-existing local users on startup. The default value is `false`.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- default_room_options: `Options`
  Define the default room options. Note that the creator of a room can modify the options of his room at any time using an XMPP client with MUC capability. The `Options` are:

  - allow_change_subj: `true | false`
    Allow occupants to change the subject. The default value is `true`.

  - allow_private_messages_from_visitors: anyone | moderators | nobody Visitors can send private messages to other occupants. The default value is `anyone` which means visitors can send private messages to any occupant.

  - allow_query_users: `true | false`
    Occupants can send IQ queries to other occupants. The default value is `true`.

  - allow_subscription: `true | false`
    Allow users to subscribe to room events as described in Multi-User Chat Subscriptions. The default value is `false`.

  - allow_user_invites: `true | false`
    Allow occupants to send invitations. The default value is `false`.

  - allow_visitor_nickchange: `true | false`
    Allow visitors to change nickname. The default value is `true`.

  - allow_visitor_status: `true | false`
    Allow visitors to send status text in presence updates. If disallowed, the status text is stripped before broadcasting the presence update to all the room occupants. The default value is `true`.

  - allow_voice_requests: `true | false`
    Allow visitors in a moderated room to request voice. The default value is `true`.

  - allowpm: `anyone | participants | moderators | none`
    Who can send private messages. The default value is `anyone`.

  - anonymous: `true | false`
    The room is anonymous: occupants don’t see the real JIDs of other occupants. Note that the room moderators can always see the real JIDs of the occupants. The default value is `true`.

  - captcha_protected: `true | false`
    When a user tries to join a room where they have no affiliation (not owner, admin or member), the room requires them to fill a CAPTCHA challenge (see section CAPTCHA in order to accept their join in the room. The default value is `false`.

  - description: `Room Description`
    Short description of the room. The default value is an empty string.

  - enable_hats: `true | false`
    `Note` about this option: improved in 25.10. Allow extended roles as defined in XEP-0317: Hats. For ejabberd older than 25.10 see the MUC Hats page. The default value is `true`.

  - lang: `Language`
    Preferred language for the discussions in the room. The language format should conform to RFC 5646. There is no value by default.

  - logging: `true | false`
    The public messages are logged using mod_muc_log. The default value is `false`.

  - mam: `true | false`
    Enable message archiving. Implies mod_mam is enabled. The default value is `false`.

  - max_users: `Number`
    Maximum number of occupants in the room. The default value is `200`.

  - members_by_default: `true | false`
    The occupants that enter the room are participants by default, so they have "voice". The default value is `true`.

  - members_only: `true | false`
    Only members of the room can enter. The default value is `false`.

  - moderated: `true | false`
    Only occupants with "voice" can send public messages. The default value is `true`.

  - password: `Password`
    Password of the room. Implies option `password_protected` set to `true`. There is no default value.

  - password_protected: `true | false`
    The password is required to enter the room. The default value is `false`.

  - persistent: `true | false`
    The room persists even if the last participant leaves. The default value is `false`.

  - presence_broadcast: `[Role]`
    List of roles for which presence is broadcasted. The list can contain one or several of: `moderator`, `participant`, `visitor`. The default value is shown in the example below:

    Example:

        presence_broadcast:
          - moderator
          - participant
          - visitor

  - public: `true | false`
    The room is public in the list of the MUC service, so it can be discovered. MUC admins and room participants will see private rooms in Service Discovery if their XMPP client supports this feature. The default value is `true`.

  - public_list: `true | false`
    The list of participants is public, without requiring to enter the room. The default value is `true`.

  - pubsub: `PubSub Node`
    XMPP URI of associated Publish/Subscribe node. The default value is an empty string.

  - title: `Room Title`
    A human-readable title of the room. There is no default value

  - vcard: `vCard`
    A custom vCard for the room. See the equivalent mod_muc option.The default value is an empty string.

  - vcard_xupdate: `undefined | external | AvatarHash`
    Set the hash of the avatar image. The default value is `undefined`.

  - voice_request_min_interval: `Number`
    Minimum interval between voice requests, in seconds. The default value is `1800`.

- hibernation_timeout: `infinity | Seconds`
  Timeout before hibernating the room process, expressed in seconds. The default value is `infinity`.

- history_size: `Size`
  A small history of the current discussion is sent to users when they enter the room. With this option you can define the number of history messages to keep and send to users joining the room. The value is a non-negative integer. Setting the value to `0` disables the history feature and, as a result, nothing is kept in memory. The default value is `20`. This value affects all rooms on the service. NOTE: modern XMPP clients rely on Message Archives (XEP-0313), so feel free to disable the history feature if you’re only using modern clients and have mod_mam module loaded.

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "conference.". The keyword `@HOST@` is replaced with the real virtual host name.

- max_captcha_whitelist: `Number`
  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`
  added in 21.01 This option defines the maximum number of characters that Password can have when configuring the room. The default value is `infinity`.

- max_room_desc: `Number`
  This option defines the maximum number of characters that Room Description can have when configuring the room. The default value is `infinity`.

- max_room_id: `Number`
  This option defines the maximum number of characters that Room ID can have when creating a new room. The default value is `infinity`.

- max_room_name: `Number`
  This option defines the maximum number of characters that Room Name can have when configuring the room. The default value is `infinity`.

- max_rooms_discoitems: `Number`
  When there are more rooms than this `Number`, only the non-empty ones are returned in a Service Discovery query. The default value is `100`.

- max_user_conferences: `Number`
  This option defines the maximum number of rooms that any given user can join. The default value is `100`. This option is used to prevent possible abuses. Note that this is a soft limit: some users can sometimes join more conferences in cluster configurations.

- max_users: `Number`
  This option defines at the service level, the maximum number of users allowed per room. It can be lowered in each room configuration but cannot be increased in individual room configuration. The default value is `200`.

- max_users_admin_threshold: `Number`
  This option defines the number of service admins or room owners allowed to enter the room when the maximum number of allowed occupants was reached. The default limit is `5`.

- max_users_presence: `Number`
  This option defines after how many users in the room, it is considered overcrowded. When a MUC room is considered overcrowded, presence broadcasts are limited to reduce load, traffic and excessive presence "storm" received by participants. The default value is `1000`.

- min_message_interval: `Number`
  This option defines the minimum interval between two messages send by an occupant in seconds. This option is global and valid for all rooms. A decimal value can be used. When this option is not defined, message rate is not limited. This feature can be used to protect a MUC service from occupant abuses and limit number of messages that will be broadcasted by the service. A good value for this minimum message interval is `0.4` second. If an occupant tries to send messages faster, an error is send back explaining that the message has been discarded and describing the reason why the message is not acceptable.

- min_presence_interval: `Number`
  This option defines the minimum of time between presence changes coming from a given occupant in seconds. This option is global and valid for all rooms. A decimal value can be used. When this option is not defined, no restriction is applied. This option can be used to protect a MUC service for occupants abuses. If an occupant tries to change its presence more often than the specified interval, the presence is cached by ejabberd and only the last presence is broadcasted to all occupants in the room after expiration of the interval delay. Intermediate presence packets are silently discarded. A good value for this option is `4` seconds.

- name: `string()`
  The value of the service name. This name is only visible in some clients that support XEP-0030: Service Discovery. The default is `Chatrooms`.

- preload_rooms: `true | false`
  Whether to load all persistent rooms in memory on startup. If disabled, the room is only loaded on first participant join. The default is `true`. It makes sense to disable room preloading when the number of rooms is high: this will improve server startup time and memory consumption.

- queue_type: `ram | file`
  Same as top-level queue_type option, but applied to this module only.

- ram_db_type: `mnesia | sql`
  Same as top-level default_ram_db option, but applied to this module only.

- regexp_room_id: `string()`
  This option defines the regular expression that a Room ID must satisfy to allow the room creation. The default value is the empty string.

- room_shaper: `none | ShaperName`
  This option defines shaper for the MUC rooms. The default value is `none`.

- user_message_shaper: `none | ShaperName`
  This option defines shaper for the users messages. The default value is `none`.

- user_presence_shaper: `none | ShaperName`
  This option defines shaper for the users presences. The default value is `none`.

- vcard: `vCard`
  A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery. The value of `vCard` is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward.

  Example:

      # This XML representation of vCard:
      #   <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

This module provides commands to administer local MUC services and their MUC rooms. It also provides simple WebAdmin pages to view the existing rooms.

This module depends on mod_muc.

Available options:

- subscribe_room_many_max_users: `Number`
  added in 22.05 How many users can be subscribed to a room at once using the subscribe_room_many API. The default value is `50`.

API Tags: muc, muc_room, muc_sub

## mod_muc_log

This module enables optional logging of Multi-User Chat (MUC) public conversations to HTML. Once you enable this module, users can join a room using a MUC capable XMPP client, and if they have enough privileges, they can request the configuration form in which they can set the option to enable room logging.

Features:

- Room details are added on top of each page: room title, JID, author, subject and configuration.

- The room JID in the generated HTML is a link to join the room (using XMPP URI).

- Subject and room configuration changes are tracked and displayed.

- Joins, leaves, nick changes, kicks, bans and `/me` are tracked and displayed, including the reason if available.

- Generated HTML files are XHTML 1.0 Transitional and CSS compliant.

- Timestamps are self-referencing links.

- Links on top for quicker navigation: Previous day, Next day, Up.

- CSS is used for style definition, and a custom CSS file can be used.

- URLs on messages and subjects are converted to hyperlinks.

- Timezone used on timestamps is shown on the log files.

- A custom link can be added on top of each page.

The module depends on mod_muc.

Available options:

- access_log: `AccessName`
  This option restricts which occupants are allowed to enable or disable room logging. The default value is `muc_admin`. NOTE: for this default setting you need to have an access rule for `muc_admin` in order to take effect.

- cssfile: `Path | URL`
  With this option you can set whether the HTML files should have a custom CSS file or if they need to use the embedded CSS. Allowed values are either `Path` to local file or an `URL` to a remote file. By default a predefined CSS will be embedded into the HTML page.

- dirname: `room_jid | room_name`
  Configure the name of the room directory. If set to `room_jid`, the room directory name will be the full room JID. Otherwise, the room directory name will be only the room name, not including the MUC service name. The default value is `room_jid`.

- dirtype: `subdirs | plain`
  The type of the created directories can be specified with this option. If set to `subdirs`, subdirectories are created for each year and month. Otherwise, the names of the log files contain the full date, and there are no subdirectories. The default value is `subdirs`.

- file_format: `html | plaintext`
  Define the format of the log files: `html` stores in HTML format, `plaintext` stores in plain text. The default value is `html`.

- file_permissions: `{mode: Mode, group: Group}`
  Define the permissions that must be used when creating the log files: the number of the mode, and the numeric id of the group that will own the files. The default value is shown in the example below:

  Example:

      file_permissions:
        mode: 644
        group: 33

- outdir: `Path`
  This option sets the full path to the directory in which the HTML files should be stored. Make sure the ejabberd daemon user has write access on that directory. The default value is `www/muc`.

- spam_prevention: `true | false`
  If set to `true`, a special attribute is added to links that prevent their indexation by search engines. The default value is `true`, which mean that `nofollow` attributes will be added to user submitted links.

- timezone: `local | universal`
  The time zone for the logs is configurable with this option. If set to `local`, the local time, as reported to Erlang emulator by the operating system, will be used. Otherwise, UTC time will be used. The default value is `local`.

- top_link: `{URL: Text}`
  With this option you can customize the link on the top right corner of each log file. The default value is shown in the example below:

  Example:

      top_link:
        /: Home

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

## mod_muc_rtbl

added in 23.04

This module implement Real-time blocklists for MUC rooms.

It works by observing remote pubsub node conforming with specification described in https://xmppbl.org/.

Available options:

- rtbl_node: `PubsubNodeName`
  Name of pubsub node that should be used to track blocked users. The default value is `muc_bans_sha256`.

- rtbl_server: `Domain`
  Domain of xmpp server that serves block list. The default value is `xmppbl.org`

## mod_multicast

This module implements a service for XEP-0033: Extended Stanza Addressing.

Available options:

- access: `Access`
  The access rule to restrict who can send packets to the multicast service. Default value: `all`.

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "multicast.". The keyword `@HOST@` is replaced with the real virtual host name. The default value is `multicast.@HOST@`.

- limits: `Sender: Stanza: Number`
  Specify a list of custom limits which override the default ones defined in XEP-0033. Limits are defined per sender type and stanza type, where:

  - `sender` can be: `local` or `remote`.

  - `stanza` can be: `message` or `presence`.

  - `number` can be a positive integer or `infinite`.

    Example:

        # Default values:
        local:
          message: 100
          presence: 100
        remote:
          message: 20
          presence: 20

- name
  Service name to provide in the Info query to the Service Discovery. Default is `"Multicast"`.

- vcard
  vCard element to return when queried. Default value is `undefined`.

Example:

    # Only admins can send packets to multicast service
    access_rules:
      multicast:
        - allow: admin

    # If you want to allow all your users:
    access_rules:
      multicast:
        - allow

    # This allows both admins and remote users to send packets,
    # but does not allow local users
    acl:
      allservers:
        server_glob: "*"
    access_rules:
      multicast:
        - allow: admin
        - deny: local
        - allow: allservers

    modules:
      mod_multicast:
         host: multicast.example.org
         access: multicast
         limits:
           local:
             message: 40
             presence: infinite
           remote:
             message: 150

## mod_offline

This module implements XEP-0160: Best Practices for Handling Offline Messages and XEP-0013: Flexible Offline Message Retrieval. This means that all messages sent to an offline user will be stored on the server until that user comes online again. Thus it is very similar to how email works. A user is considered offline if no session presence priority > 0 are currently open.

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

Available options:

- access_max_user_messages: `AccessName`
  This option defines which access rule will be enforced to limit the maximum number of offline messages that a user can have (quota). When a user has too many offline messages, any new messages that they receive are discarded, and a <resource-constraint/> error is returned to the sender. The default value is `max_user_offline_messages`.

- bounce_groupchat: `true | false`
  This option is use the disable an optimization that avoids bouncing error messages when groupchat messages could not be stored as offline. It will reduce chat room load, without any drawback in standard use cases. You may change default value only if you have a custom module which uses offline hook after `mod_offline`. This option can be useful for both standard MUC and MucSub, but the bounce is much more likely to happen in the context of MucSub, so it is even more important to have it on large MucSub services. The default value is `false`, meaning the optimization is enabled.

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- store_empty_body: `true | false | unless_chat_state`
  Whether or not to store messages that lack a <body/> element. The default value is `unless_chat_state`, which tells ejabberd to store messages even if they lack the <body/> element, unless they only contain a chat state notification (as defined in XEP-0085: Chat State Notifications.

- store_groupchat: `true | false`
  Whether or not to store groupchat messages. The default value is `false`.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

- use_mam_for_storage: `true | false`
  This is an experimental option. By enabling the option, this module uses the `archive` table from mod_mam instead of its own spool table to retrieve the messages received when the user was offline. This allows client developers to slowly drop XEP-0160 and rely on XEP-0313 instead. It also further reduces the storage required when you enable MucSub. Enabling this option has a known drawback for the moment: most of flexible message retrieval queries don’t work (those that allow retrieval/deletion of messages by id), but this specification is not widely used. The default value is `false` to keep former behaviour as default.

Examples:

This example allows power users to have as much as 5000 offline messages, administrators up to 2000, and all the other users up to 100:

    acl:
      admin:
        user:
          - admin1@localhost
          - admin2@example.org
      poweruser:
        user:
          - bob@example.org
          - jane@example.org

    shaper_rules:
      max_user_offline_messages:
        - 5000: poweruser
        - 2000: admin
        - 100

    modules:
      ...
      mod_offline:
        access_max_user_messages: max_user_offline_messages
      ...

API Tags: 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. The default value is `undefined`.

- ping_interval: `timeout()`
  How often to send pings to connected clients, if option `send_pings` is set to `true`. If a client connection does not send or receive any stanza within this interval, a ping request is sent to the client. The default value is `1` minute.

- send_pings: `true | false`
  If this option is set to `true`, the server sends pings to connected clients that are not active in a given interval defined in `ping_interval` option. This is useful to keep client connections alive or checking availability. The default value is `false`.

- timeout_action: `none | kill`
  What to do when a client does not answer to a server ping request in less than period defined in `ping_ack_timeout` option: `kill` means destroying the underlying connection, `none` means to do nothing. NOTE: when mod_stream_mgmt is loaded and stream management is enabled by a client, killing the client connection doesn’t mean killing the client session - the session will be kept alive in order to give the client a chance to resume it. The default value is `none`.

Example:

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

## 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 time defined in `interval` option. Please note that two users subscribing to each other usually generate 4 stanzas, so the recommended value is `4` or more. The default value is `5`.

- interval: `timeout()`
  The time interval. The default value is `1` minute.

Example:

    modules:
      mod_pres_counter:
        count: 5
        interval: 30 secs

## 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 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_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 top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

API Tags: private

## mod_privilege

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`. The default value is `none`.

  - get: `AccessName`
    Allows sending IQ stanzas of type `get`. The default value is `none`.

  - set: `AccessName`
    Allows sending IQ stanzas of type `set`. The default value 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. The default value is `none`.

- presence: `Options`
  This option defines permissions for presences. By default no permissions are given. The `Options` are:

  - managed_entity: `AccessName`
    An access rule that gives permissions to the component to receive server presences. The default value is `none`.

  - roster: `AccessName`
    An access rule that gives permissions to the component to receive the presence of both the users and the contacts in their roster. The default value is `none`.

- roster: `Options`
  This option defines roster permissions. By default no permissions are given. The `Options` are:

  - both: `AccessName`
    Sets read/write access to a user’s roster. The default value is `none`.

  - get: `AccessName`
    Sets read access to a user’s roster. The default value is `none`.

  - set: `AccessName`
    Sets write access to a user’s roster. The default value is `none`.

Example:

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

## mod_providers

added in 25.08

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

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

To use this module, in addition to adding it to the `modules` section, you must also enable it in `listen` → `ejabberd_http` → request_handlers. Notice you should set in ejabberd_http the option tls enabled.

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.

Available options:

- access: `AccessName`
  Defines an access rule for file transfer initiators. The default value is `all`. You may want to restrict access to the users of your server only, in order to avoid abusing your proxy by the users of remote servers.

- auth_type: `anonymous | plain`
  SOCKS5 authentication type. The default value is `anonymous`. If set to `plain`, ejabberd will use authentication backend as it would for SASL PLAIN.

- host
  Deprecated. Use `hosts` instead.

- hostname: `Host`
  Defines a hostname offered by the proxy when establishing a session with clients. This is useful when you run the proxy behind a NAT. The keyword `@HOST@` is replaced with the virtual host name. The default is to use the value of `ip` option. Examples: `proxy.mydomain.org`, `200.150.100.50`.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "proxy.". The keyword `@HOST@` is replaced with the real virtual host name.

- ip: `IPAddress`
  This option specifies which network interface to listen for. The default value is an IP address of the service’s DNS name, or, if fails, `127.0.0.1`.

- max_connections: `pos_integer() | infinity`
  Maximum number of active connections per file transfer initiator. The default value is `infinity`.

- name: `Name`
  The value of the service name. This name is only visible in some clients that support XEP-0030: Service Discovery. The default is "SOCKS5 Bytestreams".

- port: `1..65535`
  A port number to listen for incoming connections. The default value is `7777`.

- ram_db_type: `mnesia | redis | sql`
  Same as top-level default_ram_db option, but applied to this module only.

- recbuf: `Size`
  A size of the buffer for incoming packets. If you define a shaper, set the value of this option to the size of the shaper in order to avoid traffic spikes in file transfers. The default value is `65536` bytes.

- shaper: `Shaper`
  This option defines a shaper for the file transfer peers. A shaper with the maximum bandwidth will be selected. The default is `none`, i.e. no shaper.

- sndbuf: `Size`
  A size of the buffer for outgoing packets. If you define a shaper, set the value of this option to the size of the shaper in order to avoid traffic spikes in file transfers. The default value is `65536` bytes.

- vcard: `vCard`
  A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery. The value of `vCard` is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward.

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.

Available options:

- access_createnode: `AccessName`
  This option restricts which users are allowed to create pubsub nodes using `acl` and `access`. By default any account in the local ejabberd server is allowed to create pubsub nodes. The default value is: `all`.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- default_node_config: `List of Key:Value`
  To override default node configuration, regardless of node plugin. Value is a list of key-value definition. Node configuration still uses default configuration defined by node plugin, and overrides any items by value defined in this configurable list.

- force_node_config: `List of Node and the list of its Key:Value`
  Define the configuration for given nodes. The default value is: `[]`.

  Example:

      force_node_config:
        ## Avoid buggy clients to make their bookmarks public
        storage:bookmarks:
          access_model: whitelist

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "pubsub.". The keyword `@HOST@` is replaced with the real virtual host name.

- ignore_pep_from_offline: `false | true`
  To specify whether or not we should get last published PEP items from users in our roster which are offline when we connect. Value is `true` or `false`. If not defined, pubsub assumes true so we only get last items of online contacts.

- last_item_cache: `false | true`
  To specify whether or not pubsub should cache last items. Value is `true` or `false`. If not defined, pubsub does not cache last items. On systems with not so many nodes, caching last items speeds up pubsub and allows you to raise the user connection rate. The cost is memory usage, as every item is stored in memory.

- max_item_expire_node: `timeout() | infinity`
  added in 21.12 Specify the maximum item epiry time. Default value is: `infinity`.

- max_items_node: `non_neg_integer() | infinity`
  Define the maximum number of items that can be stored in a node. Default value is: `1000`.

- max_nodes_discoitems: `pos_integer() | infinity`
  The maximum number of nodes to return in a discoitem response. The default value is: `100`.

- max_subscriptions_node: `MaxSubs`
  Define the maximum number of subscriptions managed by a node. Default value is no limitation: `undefined`.

- name: `Name`
  The value of the service name. This name is only visible in some clients that support XEP-0030: Service Discovery. The default is `vCard User Search`.

- nodetree: `Nodetree`
  To specify which nodetree to use. If not defined, the default pubsub nodetree is used: `tree`. Only one nodetree can be used per host, and is shared by all node plugins.

  - `tree` nodetree store node configuration and relations on the database. `flat` nodes are stored without any relationship, and `hometree` nodes can have child nodes.

  - `virtual` nodetree does not store nodes on database. This saves resources on systems with tons of nodes. If using the `virtual` nodetree, you can only enable those node plugins: `[flat, pep]` or `[flat]`; any other plugins configuration will not work. Also, all nodes will have the default configuration, and this can not be changed. Using `virtual` nodetree requires to start from a clean database, it will not work if you used the default `tree` nodetree before.

- pep_mapping: `List of Key:Value`
  In this option you can provide a list of key-value to choose defined node plugins on given PEP namespace. The following example will use `node_tune` instead of `node_pep` for every PEP node with the tune namespace:

  Example:

      modules:
        ...
        mod_pubsub:
          pep_mapping:
            http://jabber.org/protocol/tune: tune
        ...

- plugins: `[Plugin, ...]`
  To specify which pubsub node plugins to use. The first one in the list is used by default. If this option is not defined, the default plugins list is: `[flat]`. PubSub clients can define which plugin to use when creating a node: add type='plugin-name`' attribute to the`create stanza element.

  - `flat` plugin handles the default behaviour and follows standard XEP-0060 implementation.

  - `pep` plugin adds extension to handle Personal Eventing Protocol (XEP-0163) to the PubSub engine. When enabled, PEP is handled automatically.

- vcard: `vCard`
  A custom vCard of the server that will be displayed by some XMPP clients in Service Discovery. The value of `vCard` is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward.

  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 configuration that uses flat nodes as default, and allows use of flat, hometree and pep nodes:

    modules:
      mod_pubsub:
        access_createnode: pubsub_createnode
        max_subscriptions_node: 100
        default_node_config:
          notification_type: normal
          notify_retract: false
          max_items: 4
        plugins:
          - flat
          - pep

Using relational database requires using mod_pubsub with db_type `sql`. Only flat, hometree and pep plugins supports SQL. The following example shows previous configuration with SQL usage:

    modules:
      mod_pubsub:
        db_type: sql
        access_createnode: pubsub_createnode
        ignore_pep_from_offline: true
        last_item_cache: false
        plugins:
          - flat
          - pep

API Tags: purge

## mod_pubsub_serverinfo

added in 25.07

This module adds support for XEP-0485: PubSub Server Information to expose S2S information over the Pub/Sub service.

Active S2S connections are published to a local PubSub node. Currently the node name is hardcoded as `"serverinfo"`.

Connections that support this feature are exposed with their domain names, otherwise they are shown 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.

Please note that the module only shows S2S connections established while the module is running. If you install the module at runtime, run 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. This option is only needed if your configuration has more than one host in mod_pubsub’s `hosts` option. The default value is the first host defined in 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, for example, APNS or FCM notifications directly. Instead, it’s designed to work with so-called "app servers" operated by third-party vendors of mobile apps. Those app servers will usually trigger notification delivery to the user’s mobile device using platform-dependent backend services such as FCM or APNS.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- include_body: `true | false | Text`
  If this option is set to `true`, the message text is included with push notifications generated for incoming messages with a body. The option can instead be set to a static `Text`, in which case the specified text will be included in place of the actual message body. This can be useful to signal the app server whether the notification was triggered by a message with body (as opposed to other types of traffic) without leaking actual message contents. The default value is "New message".

- include_sender: `true | false`
  If this option is set to `true`, the sender’s JID is included with push notifications generated for incoming messages with a body. The default value is `false`.

- notify_on: `messages | all`
  added in 23.10 If this option is 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 unsure, it’s strongly recommended to stick to `all`, which is the default value.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

API Tags: 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.

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 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, ...]`
  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. 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 to register a new account. To enable this feature, configure the top-level captcha_cmd and top-level captcha_url options.

As an example usage, the users of the host `localhost` can visit the page: `https://localhost:5280/register/` It is important to include the last / character in the URL, otherwise the subpages URL will be incorrect.

This module is enabled in `listen` → `ejabberd_http` → request_handlers.

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: roster

## mod_s2s_bidi

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

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

This module enables you to create shared roster groups: groups of accounts that can see members from (other) groups in their rosters.

The big advantages of this feature are that end users do not need to manually add all users to their rosters, and that they cannot permanently delete users from the shared roster groups. A shared roster group can have members from any XMPP server, but the presence will only be available from and to members of the same virtual host where the group is created. It still allows the users to have / add their own contacts, as it does not replace the standard roster. Instead, the shared roster contacts are merged to the relevant users at retrieval time. The standard user rosters thus stay unmodified.

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

- Label: Used in the rosters where this group is displayed.

- Description: of the group, which has no effect.

- Members: A list of JIDs of group members, entered one per line in the Web Admin. The special member directive `@all@` represents all the registered users in the virtual host; which is only recommended for a small server with just a few hundred users. The special member directive `@online@` represents the online users in the virtual host. With those two directives, the actual list of members in those shared rosters is generated dynamically at retrieval time.

- Displayed: A list of groups that will be in the rosters of this group’s members. A group of other vhost can be identified with `groupid@vhost`.

This module depends on mod_roster. If not enabled, roster queries will return 503 errors.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql`
  Same as top-level default_db option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

Examples:

Take the case of a computer club that wants all its members seeing each other in their rosters. To achieve this, they need to create a shared roster group similar to this one:

    Name: club_members
    Label: Club Members
    Description: Members from the computer club
    Members: member1@example.org, member2@example.org, member3@example.org
    Displayed Groups: club_members

In another case we have a company which has three divisions: Management, Marketing and Sales. All group members should see all other members in their rosters. Additionally, all managers should have all marketing and sales people in their roster. Simultaneously, all marketeers and the whole sales team should see all managers. This scenario can be achieved by creating shared roster groups as shown in the following lists:

    First list:
    Name: management
    Label: Management
    Description: Management
    Members: manager1@example.org, manager2@example.org
    Displayed: management, marketing, sales

    Second list:
    Name: marketing
    Label: Marketing
    Description: Marketing
    Members: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org
    Displayed: management, marketing

    Third list:
    Name: sales
    Label: Sales
    Description: Sales
    Members: salesman1@example.org, salesman2@example.org, salesman3@example.org
    Displayed: management, sales

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

Note

`mod\_shared_roster_ldap` depends on `mod_roster` being enabled. Roster queries will return `503` errors if `mod_roster` is not enabled.

The module accepts many configuration options. Some of them, if unspecified, default to the values specified for the top level of configuration. This lets you avoid specifying, for example, the bind password in multiple places.

- Filters: `ldap_rfilter`, `ldap_ufilter`, `ldap_gfilter`, `ldap_filter`. These options specify LDAP filters used to query for shared roster information. All of them are run against the ldap_base.

- Attributes: `ldap_groupattr`, `ldap_groupdesc`, `ldap_memberattr`, `ldap_userdesc`, `ldap_useruid`. These options specify the names of the attributes which hold interesting data in the entries returned by running filters specified with the filter options.

- Control parameters: `ldap_auth_check`, `ldap\_group\_cache_validity`, `ldap_memberattr_format`, `ldap\_memberattr\_format\_re`, `ldap_user_cache_validity`. These parameters control the behaviour of the module.

- Connection parameters: The module also accepts the connection parameters, all of which default to the top-level parameter of the same name, if unspecified. See LDAP Connection section for more information about them.

Check also the Configuration examples section to get details about retrieving the roster, and configuration examples including Flat DIT and Deep DIT.

Available options:

- cache_life_time
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed
  Same as top-level cache_missed option, but applied to this module only.

- cache_size
  Same as top-level cache_size option, but applied to this module only.

- ldap_auth_check: `true | false`
  Whether the module should check (via the ejabberd authentication subsystem) for existence of each user in the shared LDAP roster. Set to `false` if you want to disable the check. Default value is `true`.

- ldap_backups
  Same as top-level ldap_backups option, but applied to this module only.

- ldap_base
  Same as top-level ldap_base option, but applied to this module only.

- ldap_deref_aliases
  Same as top-level ldap_deref_aliases option, but applied to this module only.

- ldap_encrypt
  Same as top-level ldap_encrypt option, but applied to this module only.

- ldap_filter
  Additional filter which is AND-ed together with "User Filter" and "Group Filter". For more information check the LDAP Filters section.

- ldap_gfilter
  "Group Filter", used when retrieving human-readable name (a.k.a. "Display Name") and the members of a group. See also the parameters `ldap_groupattr`, `ldap_groupdesc` and `ldap_memberattr`. If unspecified, defaults to the top-level parameter of the same name. If that one also is unspecified, then the filter is constructed exactly like "User Filter".

- ldap_groupattr
  The name of the attribute that holds the group name, and that is used to differentiate between them. Retrieved from results of the "Roster Filter" and "Group Filter". Defaults to `cn`.

- ldap_groupdesc
  The name of the attribute which holds the human-readable group name in the objects you use to represent groups. Retrieved from results of the "Group Filter". Defaults to whatever `ldap_groupattr` is set.

- ldap_memberattr
  The name of the attribute which holds the IDs of the members of a group. Retrieved from results of the "Group Filter". Defaults to `memberUid`. The name of the attribute differs depending on the objectClass you use for your group objects, for example: `posixGroup` → `memberUid`; `groupOfNames` → `member`; `groupOfUniqueNames` → `uniqueMember`.

- ldap_memberattr_format
  A globbing format for extracting user ID from the value of the attribute named by `ldap_memberattr`. Defaults to `%u`, which means that the whole value is the member ID. If you change it to something different, you may also need to specify the User and Group Filters manually; see section Filters.

- ldap_memberattr_format_re
  A regex for extracting user ID from the value of the attribute named by `ldap_memberattr`. Check the LDAP Control Parameters section.

- ldap_password
  Same as top-level ldap_password option, but applied to this module only.

- ldap_port
  Same as top-level ldap_port option, but applied to this module only.

- ldap_rfilter
  So called "Roster Filter". Used to find names of all "shared roster" groups. See also the `ldap_groupattr` parameter. If unspecified, defaults to the top-level parameter of the same name. You must specify it in some place in the configuration, there is no default.

- ldap_rootdn
  Same as top-level ldap_rootdn option, but applied to this module only.

- ldap_servers
  Same as top-level ldap_servers option, but applied to this module only.

- ldap_tls_cacertfile
  Same as top-level ldap_tls_cacertfile option, but applied to this module only.

- ldap_tls_certfile
  Same as top-level ldap_tls_certfile option, but applied to this module only.

- ldap_tls_depth
  Same as top-level ldap_tls_depth option, but applied to this module only.

- ldap_tls_verify
  Same as top-level ldap_tls_verify option, but applied to this module only.

- ldap_ufilter
  "User Filter", used for retrieving the human-readable name of roster entries (usually full names of people in the roster). See also the parameters `ldap_userdesc` and `ldap_useruid`. For more information check the LDAP Filters section.

- ldap_uids
  Same as top-level ldap_uids option, but applied to this module only.

- ldap_userdesc
  The name of the attribute which holds the human-readable user name. Retrieved from results of the "User Filter". Defaults to `cn`.

- ldap_userjidattr
  The name of the attribute which is used to map user id to XMPP jid. If not specified (and that is default value of this option), user jid will be created from user id and this module host.

- ldap_useruid
  The name of the attribute which holds the ID of a roster item. Value of this attribute in the roster item objects needs to match the ID retrieved from the `ldap_memberattr` attribute of a group object. Retrieved from results of the "User Filter". Defaults to `cn`.

- use_cache
  Same as top-level use_cache option, but applied to this module only.

## mod_sic

This module adds support for XEP-0279: Server IP Check. This protocol enables a client to discover its external IP address.

Warning

The protocol extension is deferred and seems like there are no clients supporting it, so using this module is not recommended and, furthermore, the module might be removed in the future.

The module has no options.

## mod_sip

This module adds SIP proxy/registrar support for the corresponding virtual host.

Note

It is not enough to just load this module. You should also configure listeners and DNS records properly. For details see the section about the ejabberd_sip listen module in the ejabberd Documentation.

Available options:

- always_record_route: `true | false`
  Always insert "Record-Route" header into SIP messages. With this approach it is possible to bypass NATs/firewalls a bit more easily. The default value is `true`.

- flow_timeout_tcp: `timeout()`
  The option sets a keep-alive timer for SIP outbound TCP connections. The default value is `2` minutes.

- flow_timeout_udp: `timeout()`
  The options sets a keep-alive timer for SIP outbound UDP connections. The default value is `29` seconds.

- record_route: `URI`
  When the option `always_record_route` is set to `true` or when SIP outbound is utilized, ejabberd inserts "Record-Route" header field with this `URI` into a SIP message. The default is a SIP URI constructed from the virtual host on which the module is loaded.

- routes: `[URI, ...]`
  You can set a list of SIP URIs of routes pointing to this SIP proxy server. The default is a list containing a single SIP URI constructed from the virtual host on which the module is loaded.

- via: `[URI, ...]`
  A list to construct "Via" headers for inserting them into outgoing SIP messages. This is useful if you’re running your SIP proxy in a non-standard network topology. Every `URI` element in the list must be in the form of "scheme://host:port", where "transport" must be `tls`, `tcp`, or `udp`, "host" must be a domain name or an IP address and "port" must be an internet port number. Note that all parts of the `URI` are mandatory (e.g. you cannot omit "port" or "scheme").

Example:

    modules:
      mod_sip:
        always_record_route: false
        record_route: "sip:example.com;lr"
        routes:
          - "sip:example.com;lr"
          - "sip:sip.example.com;lr"
        flow_timeout_udp: 30 sec
        flow_timeout_tcp: 1 min
        via:
          - tls://sip-tls.example.com:5061
          - tcp://sip-tcp.example.com:5060
          - udp://sip-udp.example.com:5060

## 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 seems like even a few clients that were supporting it are now abandoned. So using this module makes very little sense.

The module has no options.

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

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 top-level cache_life_time option, but applied to this module only. The default value is `48 hours`.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- max_ack_queue: `Size`
  This option specifies the maximum number of unacknowledged stanzas queued for possible retransmission. When the limit is exceeded, the client session is terminated. The allowed values are positive integers and `infinity`. You should be careful when setting this value as it should not be set too low, otherwise, you could kill sessions in a loop, before they get the chance to finish proper session initiation. It should definitely be set higher that the size of the offline queue (for example at least 3 times the value of the max offline queue and never lower than `1000`). The default value is `5000`.

- max_resume_timeout: `timeout()`
  A client may specify the period of time until a session times out if the connection is lost. During this period of time, the client may resume its session. This option limits the period of time a client is permitted to request. It must be set to a timeout equal to or larger than the default `resume_timeout`. By default, it is set to the same value as the `resume_timeout` option.

- queue_type: `ram | file`
  Same as top-level queue_type option, but applied to this module only.

- resend_on_timeout: `true | false | if_offline`
  If this option is set to `true`, any message stanzas that weren’t acknowledged by the client will be resent on session timeout. This behavior might often be desired, but could have unexpected results under certain circumstances. For example, a message that was sent to two resources might get resent to one of them if the other one timed out. Therefore, the default value for this option is `false`, which tells ejabberd to generate an error message instead. As an alternative, the option may be set to `if_offline`. In this case, unacknowledged messages are resent only if no other resource is online when the session times out. Otherwise, error messages are generated.

- resume_timeout: `timeout()`
  This option configures the (default) period of time until a session times out if the connection is lost. During this period of time, a client may resume its session. Note that the client may request a different timeout value, see the `max_resume_timeout` option. Setting it to `0` effectively disables session resumption. The default value is `5` minutes.

## mod_stun_disco

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.

Available options:

- access: `AccessName`
  This option defines which access rule will be used to control who is allowed to discover STUN/TURN services and to request temporary credentials. The default value is `local`.

- credentials_lifetime: `timeout()`
  The lifetime of temporary credentials offered to clients. If ejabberd’s built-in TURN service is used, TURN relays allocated using temporary credentials will be terminated shortly after the credentials expired. The default value is `12 hours`. Note that restarting the ejabberd node invalidates any temporary credentials offered before the restart unless a `secret` is specified (see below).

- offer_local_services: `true | false`
  This option specifies whether local STUN/TURN services configured as ejabberd listeners should be announced automatically. Note that this will not include TLS-enabled services, which must be configured manually using the `services` option (see below). For non-anonymous TURN services, temporary credentials will be offered to the client. The default value is `true`.

- secret: `Text`
  The secret used for generating temporary credentials. If this option isn’t specified, a secret will be auto-generated. However, a secret must be specified explicitly if non-anonymous TURN services running on other ejabberd nodes and/or external TURN `services` are configured. Also note that auto-generated secrets are lost when the node is restarted, which invalidates any credentials offered before the restart. Therefore, it’s recommended to explicitly specify a secret if clients cache retrieved credentials (for later use) across service restarts.

- services: `[Service, ...]`
  The list of services offered to clients. This list can include STUN/TURN services running on any ejabberd node and/or external services. However, if any listed TURN service not running on the local ejabberd node requires authentication, a `secret` must be specified explicitly, and must be shared with that service. This will only work with ejabberd’s built-in STUN/TURN server and with external servers that support the same REST API For Access To TURN Services. Unless the `offer_local_services` is set to `false`, the explicitly listed services will be offered in addition to those announced automatically.

  - host: `Host`
    The hostname or IP address the STUN/TURN service is listening on. For non-TLS services, it’s recommended to specify an IP address (to avoid additional DNS lookup latency on the client side). For TLS services, the hostname (or IP address) should match the certificate. Specifying the `host` option is mandatory.

  - port: `1..65535`
    The port number the STUN/TURN service is listening on. The default port number is 3478 for non-TLS services and 5349 for TLS services.

  - restricted: `true | false`
    This option determines whether temporary credentials for accessing the service are offered. The default is `false` for STUN/STUNS services and `true` for TURN/TURNS services.

  - transport: `tcp | udp`
    The transport protocol supported by the service. The default is `udp` for non-TLS services and `tcp` for TLS services.

  - type: `stun | turn | stuns | turns`
    The type of service. Must be `stun` or `turn` for non-TLS services, `stuns` or `turns` for TLS services. The default type is `stun`.

  Example:

      services:
        -
          host: 203.0.113.3
          port: 3478
          type: stun
          transport: udp
          restricted: false
        -
          host: 203.0.113.3
          port: 3478
          type: turn
          transport: udp
          restricted: true
        -
          host: 2001:db8::3
          port: 3478
          type: stun
          transport: udp
          restricted: false
        -
          host: 2001:db8::3
          port: 3478
          type: turn
          transport: udp
          restricted: true
        -
          host: server.example.com
          port: 5349
          type: turns
          transport: tcp
          restricted: true

## mod_time

This module adds support for XEP-0202: Entity Time. In other words, the module reports server’s system time.

The module has no options.

## mod_vcard

This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in XEP-0054: vcard-temp. The module also implements an uncomplicated Jabber User Directory based on the vCards of these users. Moreover, it enables the server to send its vCard when queried.

Available options:

- allow_return_all: `true | false`
  This option enables you to specify if search operations with empty input fields should return all users who added some information to their vCard. The default value is `false`.

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- db_type: `mnesia | sql | ldap`
  Same as top-level default_db option, but applied to this module only.

- host
  Deprecated. Use `hosts` instead.

- hosts: `[Host, ...]`
  This option defines the Jabber IDs of the service. If the `hosts` option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "vjud.". The keyword `@HOST@` is replaced with the real virtual host name.

- matches: `pos_integer() | infinity`
  With this option, the number of reported search results can be limited. If the option’s value is set to `infinity`, all search results are reported. The default value is `30`.

- name: `Name`
  The value of the service name. This name is only visible in some clients that support XEP-0030: Service Discovery. The default is `vCard User Search`.

- search: `true | false`
  This option specifies whether the search functionality is enabled or not. If disabled, the options `hosts`, `name` and `vcard` will be ignored and the Jabber User Directory service will not appear in the Service Discovery item list. The default value is `false`.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

- vcard: `vCard`
  A custom vCard of the server that will be displayed by some XMPP clients in Service Discovery. The value of `vCard` is a YAML map constructed from an XML representation of vCard. Since the representation has no attributes, the mapping is straightforward.

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

Available options for `mnesia` backend:

- search_all_hosts: `true | false`
  Whether to perform search on all virtual hosts or not. The default value is `true`.

## mod_vcard_xupdate

The user’s client can store an avatar in the user vCard. The vCard-Based Avatars protocol (XEP-0153) provides a method for clients to inform the contacts what is the avatar hash value. However, simple or small clients may not implement that protocol.

If this module is enabled, all the outgoing client presence stanzas get automatically the avatar hash on behalf of the client. So, the contacts receive the presence stanzas with the `Update Data` described in XEP-0153 as if the client would had inserted it itself. If the client had already included such element in the presence stanza, it is replaced with the element generated by ejabberd.

By enabling this module, each vCard modification produces a hash recalculation, and each presence sent by a client produces hash retrieval and a presence stanza rewrite. For this reason, enabling this module will introduce a computational overhead in servers with clients that change frequently their presence. However, the overhead is significantly reduced by the use of caching, so you probably don’t want to set `use_cache` to `false`.

The module depends on mod_vcard.

Note

Nowadays XEP-0153 is used mostly as "read-only", i.e. modern clients don’t publish their avatars inside vCards. Thus in the majority of cases the module is only used along with mod_avatar for providing backward compatibility.

Available options:

- cache_life_time: `timeout()`
  Same as top-level cache_life_time option, but applied to this module only.

- cache_missed: `true | false`
  Same as top-level cache_missed option, but applied to this module only.

- cache_size: `pos_integer() | infinity`
  Same as top-level cache_size option, but applied to this module only.

- use_cache: `true | false`
  Same as top-level use_cache option, but applied to this module only.

## mod_version

This module implements XEP-0092: Software Version. Consequently, it answers ejabberd’s version when queried.

Available options:

- show_os: `true | false`
  Should the operating system be revealed or not. The default value is `true`.