EJABBERD.YML(5) EJABBERD.YML(5) NAME ejabberd.yml - main configuration file for ejabberd. SYNOPSIS ejabberd.yml DESCRIPTION The configuration file is written in YAML language. Warning YAML is indentation sensitive, so make sure you respect indentation, or otherwise you will get pretty cryptic configuration errors. Logically, configuration options are split into 3 main categories: Modules, Listeners and everything else called Top Level options. Thus this document is split into 3 main chapters describing each category separately. So, the contents of ejabberd.yml will typically look like this: hosts: - example.com - domain.tld loglevel: info ... listen: - port: 5222 module: ejabberd_c2s ... modules: mod_roster: {} ... Any configuration error (such as syntax error, unknown option or invalid option value) is fatal in the sense that ejabberd will refuse to load the whole configuration file and will not start or will abort configuration re- load. All options can be changed in runtime by running ejabberdctl reload-config command. Configuration reload is atomic: either all options are accepted and applied simultaneously or the new configuration is refused without any impact on currently running configuration. Some options can be specified for particular virtual host(s) only using host_config or append_host_config options. Such options are called local. Examples are modules, auth_method and default_db. The options that cannot be defined per virtual host are called global. Examples are loglevel, cert- files and listen. It is a configuration mistake to put global options under host_config or append_host_config section - ejabberd will refuse to load such configuration. It is not recommended to write ejabberd.yml from scratch. Instead it is better to start from "default" configuration file available at https://github.com/processone/ejabberd/blob/26.07/ejabberd.yml.example. Once you get ejabberd running you can start changing configuration options to meet your requirements. Note that this document is intended to provide comprehensive description of all configuration options that can be consulted to understand the meaning of a particular option, its format and possible values. It will be quite hard to understand how to configure ejabberd by reading this document only - for this purpose the reader is recommended to read online Configuration Guide available at https://docs.ejabberd.im/admin/configuration. TOP LEVEL OPTIONS This section describes top level options of ejabberd 26.07. The options that changed in this version are marked with dh . access_rules: {AccessName: {allow|deny: ACLName|ACLDefinition}} This option defines basic.md#access-rules|Access Rules. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from access options of ejabberd modules). Each rule definition may contain arbitrary number of allow or deny sec- tions, and each section may contain any number of ACL rules (see acl option). There are no access rules defined by default. Example: access_rules: configure: allow: admin something: deny: someone allow: all s2s_banned: deny: problematic_hosts deny: banned_forever deny: ip: 222.111.222.111/32 deny: ip: 111.222.111.222/32 allow: all xmlrpc_access: allow: user: peter@example.com allow: user: ivone@example.com allow: user: bot@example.com ip: 10.0.0.0/24 acl: {ACLName: {ACLType: ACLValue}} This option defines ../configuration/basic.md#acl|access control lists: named sets of rules which are used to match against different targets (such as a JID or an IP address). Every set of rules has name ACLName: it can be any string except all or none (those are predefined names for the rules that match all or nothing respectively). The name ACLName can be referenced from other parts of the configuration file, for example in access_rules option. The rules of ACLName are represented by mapping {ACLType: ACLValue}. These can be one of the following: ip: Network The rule matches any IP address from the Network. node_glob: Pattern Same as node_regexp, but matching is performed on a specified Pat- tern according to the rules used by the Unix shell. node_regexp: user_regexp@server_regexp The rule matches any JID with node part matching regular expression user_regexp and server part matching regular expression server_reg- exp. resource: Resource The rule matches any JID with a resource Resource. resource_glob: Pattern Same as resource_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell. resource_regexp: Regexp The rule matches any JID with a resource that matches regular ex- pression Regexp. server: Server The rule matches any JID from server Server. The value of Server must be a valid hostname or an IP address. server_glob: Pattern Same as server_regexp, but matching is performed on a specified Pattern according to the rules used by the Unix shell. server_regexp: Regexp The rule matches any JID from the server that matches regular ex- pression Regexp. user: Username If Username is in the form of "user@server", the rule matches a JID against this value. Otherwise, if Username is in the form of "user", the rule matches any JID that has Username in the node part as long as the server part of this JID is any virtual host served by ejabberd. user_glob: Pattern Same as user_regexp, but matching is performed on a specified Pat- tern according to the rules used by the Unix shell. user_regexp: Regexp If Regexp is in the form of "regexp@server", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is equal to "server". If Regexp is in the form of "regexp", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is any virtual host served by ejabberd. acme: Options basic.md#acme|ACME configuration, to automatically obtain SSL certifi- cates for the domains served by ejabberd, which means that certificate requests and renewals are performed to some CA server (aka "ACME server") in a fully automated mode. The Options are: auto: true | false Whether to automatically request certificates for all configured domains (that yet have no a certificate) on server start or config- uration reload. The default is true. ca_url: URL The ACME directory URL used as an entry point for the ACME server. The default value is https://acme-v02.api.letsencrypt.org/directory - the directory URL of Let's Encrypt authority. cert_type: rsa | ec A type of a certificate key. Available values are ec and rsa for EC and RSA certificates respectively. It's better to have RSA certifi- cates for the purpose of backward compatibility with legacy clients and servers, thus the default is rsa. contact: [Contact, ...] A list of contact addresses (typically emails) where an ACME server will send notifications when problems occur. The value of Contact must be in the form of "scheme:address" (e.g. "mailto:user@do- main.tld"). The default is an empty list which means an ACME server will send no notices. Example: acme: ca_url: https://acme-v02.api.letsencrypt.org/directory contact: - mailto:admin@domain.tld - mailto:bot@domain.tld auto: true cert_type: rsa allow_contrib_modules: true | false Whether to allow installation of third-party modules or not. See ../../admin/guide/modules.md#ejabberd-modules|ejabberd-modules documen- tation section. The default value is true. allow_multiple_connections: true | false This option is only used when the anonymous mode is enabled. Setting it to true means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect. This option is only useful in very special occasions. The default value is false. anonymous_protocol: login_anon | sasl_anon | both Define what authentication.md#anonymous-login-and-sasl-anonymous|anony- mous protocol will be used: * login_anon means that the anonymous login method will be used. * sasl_anon means that the SASL Anonymous method will be used. * both means that SASL Anonymous and login anonymous are both en- abled. The default value is sasl_anon. api_permissions: [Permission, ...] Define the permissions for API access. Please consult the ejabberd Docs web a For Developers a ejabberd ReST API a ../../developer/ejab- berd-api/permissions.md|API Permissions. append_host_config: {Host: Options} Add a few specific options to a certain ../configuration/basic.md#vir- tual-hosting|virtual host. auth_cache_life_time: timeout() Same as cache_life_time, but applied to authentication cache only. If not set, the value from cache_life_time will be used. auth_cache_missed: true | false Same as cache_missed, but applied to authentication cache only. If not set, the value from cache_missed will be used. auth_cache_size: pos_integer() | infinity Same as cache_size, but applied to authentication cache only. If not set, the value from cache_size will be used. auth_external_user_exists_check: true | false Note about this option: added in 23.10. Supplement check for user exis- tence based on mod_last data, for authentication methods that don't have a way to reliably tell if a user exists (like is the case for jwt and certificate based authentication). This helps with processing of- fline message for those users. The default value is true. auth_method: [mnesia | sql | anonymous | external | jwt | ldap | pam, ...] A list of authentication.md|authentication methods to use. If several methods are defined, authentication is considered successful as long as authentication of at least one of the methods succeeds. The default value is [mnesia]. auth_opts: [Option, ...] This is used by the contributed module ejabberd_auth_http that can be installed from the ../../admin/guide/modules.md#ejabberd-contrib|ejab- berd-contrib Git repository. Please refer to that module's README file for details. auth_password_format: plain | scram Note about this option: improved in 20.01. The option defines in what format the users passwords are stored, plain text or in authentica- tion.md#scram|SCRAM format: * plain: The password is stored as plain text in the database. This is risky because the passwords can be read if your database gets compromised. This is the default value. This format allows clients to authenticate using: the old Jabber Non-SASL (XEP-0078), SASL PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1/256/512(-PLUS). * scram: The password is not stored, only some information required to verify the hash provided by the client. It is impossible to ob- tain the original plain password from the stored information; for this reason, when this value is configured it cannot be changed to plain anymore. This format allows clients to authenticate using: SASL PLAIN and SASL SCRAM-SHA-1/256/512(-PLUS). The SCRAM variant depends on the auth_scram_hash option. The default value is plain. auth_password_types_hidden_in_sasl1: [plain | scram_sha1 | scram_sha256 | scram_sha512] Note about this option: added in 25.07. List of password types that should not be offered in SASL1 authenticatication. Because SASL1, un- like SASL2, can't have list of available mechanisms tailored to indi- vidual user, it's possible that offered mechanisms will not be compati- ble with stored password, especially if new password type was added re- cently. This option allows disabling offering some mechanisms in SASL1, to a time until new password type will be available for all users. auth_scram_hash: sha | sha256 | sha512 Hash algorithm that should be used to store password in authentica- tion.md#scram|SCRAM format. You shouldn't change this if you already have passwords generated with a different algorithm - users that have such passwords will not be able to authenticate. The default value is sha. auth_stored_password_types: [plain | scram_sha1 | scram_sha256 | scram_sha512] Note about this option: added in 25.03. List of password types that should be stored simultaneously for each user in database. When the user sets the account password, database will be updated to store the password in formats compatible with each type listed here. This can be used to migrate user passwords to a more secure format. If this option if set, it will override values set in auth_scram_hash and auth_pass- word_format options. The default value is []. auth_use_cache: true | false Same as use_cache, but applied to authentication cache only. If not set, the value from use_cache will be used. c2s_cafile: Path Full path to a file containing one or more CA certificates in PEM for- mat. All client certificates should be signed by one of these root CA certificates and should contain the corresponding JID(s) in subjectAlt- Name field. There is no default value. You can use host_config to specify this option per-vhost. To set a specific file per listener, use the listener's listen-op- tions.md#cafile|cafile option. Please notice that c2s_cafile overrides the listener's cafile option. c2s_ciphers: [Cipher, ...] A list of OpenSSL ciphers to use for c2s connections. The default value is shown in the example below: Example: c2s_ciphers: - HIGH - "!aNULL" - "!eNULL" - "!3DES" - "@STRENGTH" c2s_dhfile: Path Full path to a file containing custom DH parameters to use for c2s con- nections. Such a file could be created with the command "openssl dh- param -out dh.pem 2048". If this option is not specified, 2048-bit MODP Group with 256-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2.3. c2s_protocol_options: [Option, ...] List of general SSL options to use for c2s connections. These map to OpenSSL's set_options(). The default value is shown in the example be- low: Example: c2s_protocol_options: - no_sslv3 - cipher_server_preference - no_compression c2s_tls_compression: true | false Whether to enable or disable TLS compression for c2s connections. The default value is false. ca_file: Path Path to a file of CA root certificates. The default is to use system defined file if possible. For server connections, this ca_file option is overridden by the s2s_cafile option. cache_life_time: timeout() The time of a cached item to keep in cache. Once it's expired, the cor- responding item is erased from cache. The default value is 1 hour. Sev- eral modules have a similar option; and some core ejabberd parts sup- port similar options too, see auth_cache_life_time, oauth_cache_life_time, router_cache_life_time, and sm_cache_life_time. cache_missed: true | false Whether or not to cache missed lookups. When there is an attempt to lookup for a value in a database and this value is not found and the option is set to true, this attempt will be cached and no attempts will be performed until the cache expires (see cache_life_time). Usually you don't want to change it. Default is true. Several modules have a simi- lar option; and some core ejabberd parts support similar options too, see auth_cache_missed, oauth_cache_missed, router_cache_missed, and sm_cache_missed. cache_size: pos_integer() | infinity A maximum number of items (not memory!) in cache. The rule of thumb, for all tables except rosters, you should set it to the number of maxi- mum online users you expect. For roster multiply this number by 20 or so. If the cache size reaches this threshold, it's fully cleared, i.e. all items are deleted, and the corresponding warning is logged. You should avoid frequent cache clearance, because this degrades perfor- mance. The default value is 1000. Several modules have a similar op- tion; and some core ejabberd parts support similar options too, see auth_cache_size, oauth_cache_size, router_cache_size, and sm_cache_size. captcha_cmd: Path | ModuleName Note about this option: improved in 23.01. Full path to a script that generates basic.md#captcha|CAPTCHA images. The keyword @VERSION@ is re- placed with ejabberd version number in XX.YY format. The keyword @SEMVER@ is replaced with ejabberd version number in semver format when compiled with Elixir's mix, or XX.YY format otherwise. Alternatively, it can be the name of a module that implements ejabberd CAPTCHA sup- port. There is no default value: when this option is not set, CAPTCHA functionality is completely disabled. Examples: When using the ejabberd installers or container image, the example captcha scripts can be used like this: captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh captcha_host: String Deprecated. Use captcha_url instead. captcha_limit: pos_integer() | infinity Maximum number of basic.md#captcha|CAPTCHA generated images per minute for any given JID. The option is intended to protect the server from CAPTCHA DoS. The default value is infinity. captcha_url: URL | auto | undefined Note about this option: improved in 23.04. An URL where ba- sic.md#captcha|CAPTCHA requests should be sent. NOTE: you need to con- figure request_handlers for ejabberd_http listener as well. If set to auto, it builds the URL using a request_handler already enabled, with encryption if available. If set to undefined, it builds the URL using the deprecated captcha_host + /captcha. The default value is auto. certfiles: [Path, ...] The option accepts a list of file paths (optionally with wildcards) containing either PEM certificates or PEM private keys. At startup or configuration reload, ejabberd reads all certificates from these files, sorts them, removes duplicates, finds matching private keys and then rebuilds full certificate chains for the use in TLS connections. Use this option when TLS is enabled in either of ejabberd listeners: ejab- berd_c2s, ejabberd_http and so on. NOTE: if you modify the certificate files or change the value of the option, run ejabberdctl reload-config in order to rebuild and reload the certificate chains. Examples: If you use Let's Encrypt certificates for your domain "domain.tld", the configuration will look like this: certfiles: - /etc/letsencrypt/live/domain.tld/fullchain.pem - /etc/letsencrypt/live/domain.tld/privkey.pem cluster_backend: Backend A database backend to use for storing information about cluster. The only available value so far is mnesia. cluster_nodes: [Node, ...] A list of Erlang nodes to connect on ejabberd startup. This option is mostly intended for ejabberd customization and sophisticated setups. The default value is an empty list. default_db: mnesia | sql database.md#default-database|Default database to store persistent data in ejabberd. Some components can be configured with specific toplevel options like oauth_db_type. Many modules can be configured with spe- cific module options, usually named db_type. The default value is mne- sia. default_ram_db: mnesia | redis | sql Default volatile (in-memory) storage for ejabberd. Some components can be configured with specific toplevel options like router_db_type and sm_db_type. Some modules can be configured with specific module op- tions, usually named ram_db_type. The default value is mnesia. define_keyword: {NAME: Value} Note about this option: added in 25.03. Allows to define configuration ../configuration/file-format.md#macros-and-keywords|keywords. Example: define_keyword: SQL_USERNAME: "eja.global" host_config: localhost: define_keyword: SQL_USERNAME: "eja.localhost" sql_username: "prefix.@SQL_USERNAME@" define_macro: {NAME: Value} Note about this option: improved in 25.03. Allows to define configura- tion ../configuration/file-format.md#macros-and-keywords|macros. Example: define_macro: DEBUG: debug LOG_LEVEL: DEBUG USERBOB: user: bob@localhost loglevel: LOG_LEVEL acl: admin: USERBOB disable_sasl_mechanisms: [Mechanism, ...] Specify a list of SASL mechanisms (such as DIGEST-MD5 or SCRAM-SHA1) that should not be offered to the client. For convenience, the value of Mechanism is case-insensitive. The default value is an empty list, i.e. no mechanisms are disabled by default. disable_sasl_scram_downgrade_protection: true | false Allows to disable sending data required by XEP-0474: SASL SCRAM Down- grade Protection. There are known buggy clients (like those that use strophejs 1.6.2) which will not be able to authenticatate when servers sends data from that specification. This options allows server to dis- able it to allow even buggy clients connects, but in exchange decrease MITM protection. The default value of this option is false which en- ables this extension. domain_balancing: {Domain: Options} An algorithm to ../guide/clustering.md#service-load-balancing|load-bal- ance the components that are plugged on an ejabberd cluster. It means that you can plug one or several instances of the same component on each ejabberd node and that the traffic will be automatically distrib- uted. The algorithm to deliver messages to the component(s) can be specified by this option. For any component connected as Domain, avail- able Options are: component_number: 2..1000 The number of components to balance. type: Value How to deliver stanzas to connected components. The default value is random. Possible values: - bare_destination by the bare JID (without resource) of the packet's to attribute - bare_source by the bare JID (without resource) of the packet's from attribute is used - destination an instance is chosen by the full JID of the packet's to attribute - random an instance is chosen at random - source by the full JID of the packet's from attribute Example: domain_balancing: component.domain.tld: type: destination component_number: 5 transport.example.org: type: bare_source ext_api_headers: Headers String of headers (separated with commas ,) that will be provided by ejabberd when sending ReST requests. The default value is an empty string of headers: "". ext_api_http_pool_size: pos_integer() Define the size of the HTTP pool, that is, the maximum number of ses- sions that the ejabberd ReST service will handle simultaneously. The default value is: 100. ext_api_path_oauth: Path Define the base URI path when performing OAUTH ReST requests. The de- fault value is: "/oauth". ext_api_url: URL Define the base URI when performing ReST requests. The default value is: "http://localhost/api". extauth_pool_name: Name Define the pool name appendix in authentication.md#external-script|ex- ternal auth, so the full pool name will be extauth_pool_Name. The de- fault value is the hostname. extauth_pool_size: Size The option defines the number of instances of the same authentica- tion.md#external-script|external auth program to start for better load balancing. The default is the number of available CPU cores. extauth_program: Path Indicate in this option the full path to the authentication.md#exter- nal-script|external authentication script. The script must be exe- cutable by ejabberd. fqdn: Domain A fully qualified domain name that will be used in SASL DIGEST-MD5 au- thentication. The default is detected automatically. hide_sensitive_log_data: true | false A privacy option to not log sensitive data (mostly IP addresses). The default value is false for backward compatibility. host_config: {Host: Options} The option is used to redefine Options for ../configuration/ba- sic.md#virtual-hosting|virtual host Host. In the example below LDAP au- thentication method will be used on virtual host domain.tld and SQL method will be used on virtual host example.org. Example: hosts: - domain.tld - example.org auth_method: - sql host_config: domain.tld: auth_method: - ldap hosts: [Domain1, Domain2, ...] List of one or more ../configuration/basic.md#host-names|host names (or domains) that ejabberd will serve. This is a mandatory option. hosts_alias: {Alias: Host} Note about this option: added in 25.07. Define aliases for existing vhosts managed by ejabberd. An alias may be a regexp expression. This option is only consulted by the ejabberd_http listener. Example: hosts: - domain.tld - example.org hosts_alias: xmpp.domain.tld: domain.tld jabber.domain.tld: domain.tld mytest.net: example.org "exa*": example.org include_config_file: [Filename, ...] | {Filename: Options} Read and ../configuration/file-format.md#include-additional-files|in- clude additional file from Filename. If the value is provided in {File- name: Options} format, the Options must be one of the following: allow_only: [OptionName, ...] Allows only the usage of those options in the included file File- name. The options that do not match this criteria are not accepted. The default value is to include all options. disallow: [OptionName, ...] Disallows the usage of those options in the included file Filename. The options that match this criteria are not accepted. The default value is an empty list. install_contrib_modules: [Module, ...] Note about this option: added in 23.10. Modules from ../../ad- min/guide/modules.md#ejabberd-modules|ejabberd-modules to install auto- matically at start time. The default value is an empty list of modules: []. Example: install_contrib_modules: - mod_tombstones modules: mod_tombstones: {} jwt_auth_only_rule: AccessName This ACL rule defines accounts that can use only the authentica- tion.md#jwt-authentication|JWT auth method, even if others are also de- fined in the ejabberd configuration file. In other words: if there are several auth methods enabled for this host (JWT, SQL, ...), users that match this rule can only use JWT. The default value is none. jwt_jid_field: FieldName By default, the JID is defined in the "jid" JWT field. In this option you can specify other authentication.md#jwt-authentication|JWT field name where the JID is defined. jwt_key: FilePath Path to the file that contains the authentication.md#jwt-authentica- tion|JWT key. Supported file formats: * PEM format - Standard PEM-encoded keys (RSA, EC, EdDSA, etc.) * JWK (JSON Web Key) - JSON format * JWK Set - JSON with a "keys" array (but must contain exactly one key) By default there is no path defined, that is: undefined. language: Language Define the ../configuration/basic.md#default-language|default language of server strings that can be seen by XMPP clients. If an XMPP client does not possess xml:lang attribute, the specified language is used. The default value is "en". ldap_backups: [Host, ...] A list of IP addresses or DNS names of LDAP backup servers (see ../con- figuration/ldap.md#ldap-connection|LDAP connection). When no servers listed in ldap_servers option are reachable, ejabberd connects to these backup servers. The default is an empty list, i.e. no backup servers specified. Please notice that ejabberd only connects to the next server when the existing connection is lost; it doesn't detect when a previ- ously-attempted server becomes available again. ldap_base: Base LDAP base directory which stores users accounts. There is no default value: you must set the option in order for LDAP connections to work properly. ldap_deref_aliases: never | always | finding | searching Whether to dereference aliases or not. The default value is never. ldap_dn_filter: {Filter: FilterAttrs} This filter is applied on the results returned by the main filter. The filter performs an additional LDAP lookup to make the complete result. This is useful when you are unable to define all filter rules in ldap_filter. You can define "%u", "%d", "%s" and "%D" pattern variables in Filter: "%u" is replaced by a user's part of the JID, "%d" is re- placed by the corresponding domain (virtual host), all "%s" variables are consecutively replaced by values from the attributes in FilterAttrs and "%D" is replaced by Distinguished Name from the result set. There is no default value, which means the result is not filtered. WARNING: Since this filter makes additional LDAP lookups, use it only as the last resort: try to define all filter rules in ldap_filter option if possible. Example: ldap_dn_filter: "(&(name=%s)(owner=%D)(user=%u@%d))": [sn] ldap_encrypt: tls | none Whether to encrypt LDAP connection using TLS or not. The default value is none. NOTE: STARTTLS encryption is not supported. ldap_filter: Filter An LDAP filter as defined in RFC4515. There is no default value. Exam- ple: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))". NOTE: don't forget to close brackets and don't use superfluous whitespaces. Also you must not use "uid" attribute in the filter because this attribute will be appended to the filter automatically. ldap_password: Password Bind password. The default value is an empty string. ldap_port: 1..65535 Port to connect to your LDAP server. The default port is 389 if encryp- tion is disabled and 636 if encryption is enabled. ldap_rootdn: RootDN Bind Distinguished Name. The default value is an empty string, which means "anonymous connection". ldap_servers: [Host, ...] A list of IP addresses or DNS names of your LDAP servers (see ../con- figuration/ldap.md#ldap-connection|LDAP connection). ejabberd connects immediately to all of them, and reconnects infinitely if connection is lost. The default value is [localhost]. ldap_tls_cacertfile: Path A path to a file containing PEM encoded CA certificates. This option is required when TLS verification is enabled. ldap_tls_certfile: Path A path to a file containing PEM encoded certificate along with PEM en- coded private key. This certificate will be provided by ejabberd when TLS enabled for LDAP connections. There is no default value, which means no client certificate will be sent. ldap_tls_depth: Number Specifies the maximum verification depth when TLS verification is en- abled, i.e. how far in a chain of certificates the verification process can proceed before the verification is considered to be failed. Peer certificate = 0, CA certificate = 1, higher level CA certificate = 2, etc. The value 2 thus means that a chain can at most contain peer cert, CA cert, next CA cert, and an additional CA cert. The default value is 1. ldap_tls_verify: false | soft | hard This option specifies whether to verify LDAP server certificate or not when TLS is enabled. When hard is set, ejabberd doesn't proceed if the certificate is invalid. When soft is set, ejabberd proceeds even if the check has failed. The default is false, which means no checks are per- formed. ldap_uids: [Attr] | {Attr: AttrFormat} LDAP attributes which hold a list of attributes to use as alternatives for getting the JID, where Attr is an LDAP attribute which holds the user's part of the JID and AttrFormat must contain one and only one pattern variable "%u" which will be replaced by the user's part of the JID. For example, "%u@example.org". If the value is in the form of [Attr] then AttrFormat is assumed to be "%u". listen: [Options, ...] The option for listeners configuration. See the listen.md|Listen Mod- ules section for details. log_burst_limit_count: Number Note about this option: added in 22.10. The number of messages to ac- cept in log_burst_limit_window_time period before starting to drop them. Default 500 log_burst_limit_window_time: Number Note about this option: added in 22.10. The time period to rate-limit log messages by. Defaults to 1 second. log_modules_fully: [Module, ...] Note about this option: added in 23.01. List of modules that will log everything independently from the general loglevel option. log_rotate_count: Number The number of rotated log files to keep. The default value is 1, which means that only keeps ejabberd.log.0, error.log.0 and crash.log.0. log_rotate_size: pos_integer() | infinity The size (in bytes) of a log file to trigger rotation. If set to infin- ity, log rotation is disabled. The default value is 10 Mb expressed in bytes: 10485760. loglevel: none | emergency | alert | critical | error | warning | notice | info | debug Verbosity of ejabberd ../configuration/basic.md#logging|logging. The default value is info. NOTE: previous versions of ejabberd had log lev- els defined in numeric format (0..5). The numeric values are still ac- cepted for backward compatibility, but are not recommended. max_fsm_queue: Size This option specifies the maximum number of elements in the queue of the FSM (Finite State Machine). Roughly speaking, each message in such queues represents one XML stanza queued to be sent into its relevant outgoing stream. If queue size reaches the limit (because, for example, the receiver of stanzas is too slow), the FSM and the corresponding connection (if any) will be terminated and error message will be logged. The reasonable value for this option depends on your hardware configuration. The allowed values are positive integers. The default value is 10000. modules: {Module: Options} Set all the modules.md|modules configuration options. negotiation_timeout: timeout() Time to wait for an XMPP stream negotiation to complete. When timeout occurs, the corresponding XMPP stream is closed. The default value is 120 seconds. net_ticktime: timeout() This option can be used to tune tick time parameter of net_kernel. It tells Erlang VM how often nodes should check if intra-node communica- tion was not interrupted. This option must have identical value on all nodes, or it will lead to subtle bugs. Usually leaving default value of this is option is best, tweak it only if you know what you are doing. The default value is 1 minute. new_sql_schema: true | false Note about this option: obsoleted in 25.10. This option was renamed to sql_schema_multihost in ejabberd 25.10. Please update your configura- tion to use the new option name oauth_access: AccessName By default creating OAuth tokens is not allowed. To define which users can create OAuth tokens, you can refer to an ejabberd access rule in the oauth_access option. Use all to allow everyone to create tokens. oauth_cache_life_time: timeout() Same as cache_life_time, but applied to OAuth cache only. If not set, the value from cache_life_time will be used. oauth_cache_missed: true | false Same as cache_missed, but applied to OAuth cache only. If not set, the value from cache_missed will be used. oauth_cache_rest_failure_life_time: timeout() Note about this option: added in 21.01. The time that a failure in OAuth ReST is cached. The default value is infinity. oauth_cache_size: pos_integer() | infinity Same as cache_size, but applied to OAuth cache only. If not set, the value from cache_size will be used. oauth_client_id_check: allow | db | deny Define whether the client authentication is always allowed, denied, or it will depend if the client ID is present in the database. The default value is db. oauth_db_type: mnesia | sql Database backend to use for OAuth authentication. The default value is picked from default_db option, or if it's not set, mnesia will be used. oauth_expire: timeout() Time during which the OAuth token is valid, in seconds. After that amount of time, the token expires and the delegated credential cannot be used and is removed from the database. The default is 4294967 sec- onds. oauth_use_cache: true | false Same as use_cache, but applied to OAuth cache only. If not set, the value from use_cache will be used. oom_killer: true | false Enable or disable OOM (out-of-memory) killer. When system memory raises above the limit defined in oom_watermark option, ejabberd triggers OOM killer to terminate most memory consuming Erlang processes. Note that in order to maintain functionality, ejabberd only attempts to kill transient processes, such as those managing client sessions, s2s or database connections. The default value is true. oom_queue: Size Trigger OOM killer when some of the running Erlang processes have mes- sages queue above this Size. Note that such processes won't be killed if oom_killer option is set to false or if oom_watermark is not reached yet. oom_watermark: Percent A percent of total system memory consumed at which OOM killer should be activated with some of the processes possibly be killed (see oom_killer option). Later, when memory drops below this Percent, OOM killer is de- activated. The default value is 80 percents. outgoing_s2s_families: [ipv6 | ipv4, ...] Note about this option: changed in 23.01. Specify which address fami- lies to try, in what order. The default is [ipv6, ipv4] which means it first tries connecting with IPv6, if that fails it tries using IPv4. This option is obsolete and irrelevant when using ejabberd 23.01 and Erlang/OTP 22, or newer versions of them. outgoing_s2s_ipv4_address: Address Note about this option: added in 20.12. Specify the IPv4 address that will be used when establishing an outgoing S2S IPv4 connection, for ex- ample "127.0.0.1". The default value is undefined. outgoing_s2s_ipv6_address: Address Note about this option: added in 20.12. Specify the IPv6 address that will be used when establishing an outgoing S2S IPv6 connection, for ex- ample "::FFFF:127.0.0.1". The default value is undefined. outgoing_s2s_port: 1..65535 A port number to use for outgoing s2s connections when the target server doesn't have an SRV record. The default value is 5269. outgoing_s2s_timeout: timeout() The timeout in seconds for outgoing S2S connection attempts. The de- fault value is 10 seconds. pam_service: Name This option defines the authentication.md#pam-authentication|PAM ser- vice name. Refer to the PAM documentation of your operation system for more information. The default value is ejabberd. pam_userinfotype: username | jid This option defines what type of information about the user ejabberd provides to the authentication.md#pam-authentication|PAM service: only the username, or the user's JID. Default is username. pgsql_users_number_estimate: true | false Whether to use PostgreSQL estimation when counting registered users. The default value is false. queue_dir: Directory If queue_type option is set to file, use this Directory to store file queues. The default is to keep queues inside Mnesia directory. queue_type: ram | file Default type of queues in ejabberd. Modules may have its own value of the option. The value of ram means that queues will be kept in memory. If value file is set, you may also specify directory in queue_dir op- tion where file queues will be placed. The default value is ram. redis_connect_timeout: timeout() A timeout to wait for the connection to be re-established to the data- base.md#redis|Redis server. The default is 1 second. redis_db: Number database.md#redis|Redis database number. The default is 0. redis_password: Password The password to the database.md#redis|Redis server. The default is an empty string, i.e. no password. redis_pool_size: Number The number of simultaneous connections to the database.md#redis|Redis server. The default value is 10. redis_port: 1..65535 The port where the database.md#redis|Redis server is accepting connec- tions. The default is 6379. redis_queue_type: ram | file The type of request queue for the database.md#redis|Redis server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set. redis_server: Host | IP Address | Unix Socket Path Note about this option: improved in 24.12. A hostname, IP address or unix domain socket file of the database.md#redis|Redis server. Setup the path to unix domain socket like: "unix:/path/to/socket". The de- fault value is localhost. registration_timeout: timeout() This is a global option for module mod_register. It limits the fre- quency of registrations from a given IP or username. So, a user that tries to register a new account from the same IP address or JID during this time after their previous registration will receive an error with the corresponding explanation. To disable this limitation, set the value to infinity. The default value is 600 seconds. replaced_connection_timeout: timeout() Note about this option: added in 26.01. Maximum time that new session will wait for termination of session that it's replacing. This allows old session to properly sends its unavailable presences, and helps with potetnial race conditions between old and new sessions presences. resource_conflict: setresource | closeold | closenew NOTE: this option is deprecated and may be removed anytime in the fu- ture versions. The possible values match exactly the three possibili- ties described in XMPP Core: section 7.7.2.2. The default value is closeold. If the client uses old Jabber Non-SASL authentication (XEP-0078), then this option is not respected, and the action performed is closeold. rest_proxy: Host Note about this option: added in 25.07. Address of a HTTP Connect proxy used by modules issuing rest calls (like ejabberd_oauth_rest) rest_proxy_password: string() Note about this option: added in 25.07. Password used to authenticate to HTTP Connect proxy used by modules issuing rest calls (like ejab- berd_oauth_rest) rest_proxy_port: 1..65535 Note about this option: added in 25.07. Port of a HTTP Connect proxy used by modules issuing rest calls (like ejabberd_oauth_rest) rest_proxy_username: string() Note about this option: added in 25.07. Username used to authenticate to HTTP Connect proxy used by modules issuing rest calls (like ejab- berd_oauth_rest) router_cache_life_time: timeout() Same as cache_life_time, but applied to routing table cache only. If not set, the value from cache_life_time will be used. router_cache_missed: true | false Same as cache_missed, but applied to routing table cache only. If not set, the value from cache_missed will be used. router_cache_size: pos_integer() | infinity Same as cache_size, but applied to routing table cache only. If not set, the value from cache_size will be used. router_db_type: mnesia | redis | sql Database backend to use for routing information. The default value is picked from default_ram_db option, or if it's not set, mnesia will be used. router_use_cache: true | false Same as use_cache, but applied to routing table cache only. If not set, the value from use_cache will be used. rpc_timeout: timeout() A timeout for remote function calls between nodes in an ejabberd clus- ter. You should probably never change this value since those calls are used for internal needs only. The default value is 5 seconds. s2s_access: Access This basic.md#access-rules|Access Rule defines to what remote servers can s2s connections be established. The default value is all; no re- strictions are applied, it is allowed to connect s2s to/from all remote servers. s2s_cafile: Path A path to a file with CA root certificates that will be used to authen- ticate s2s connections. If not set, the value of ca_file will be used. You can use host_config to specify this option per-vhost. s2s_ciphers: [Cipher, ...] A list of OpenSSL ciphers to use for s2s connections. The default value is shown in the example below: Example: s2s_ciphers: - HIGH - "!aNULL" - "!eNULL" - "!3DES" - "@STRENGTH" s2s_dhfile: Path Full path to a file containing custom DH parameters to use for s2s con- nections. Such a file could be created with the command "openssl dh- param -out dh.pem 2048". If this option is not specified, 2048-bit MODP Group with 256-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2.3. s2s_dns_retries: Number DNS resolving retries. The default value is 2. s2s_dns_timeout: timeout() The timeout for DNS resolving. The default value is 10 seconds. s2s_max_retry_delay: timeout() The maximum allowed delay for s2s connection retry to connect after a failed connection attempt. The default value is 300 seconds (5 min- utes). s2s_protocol_options: [Option, ...] List of general SSL options to use for s2s connections. These map to OpenSSL's set_options(). The default value is shown in the example be- low: Example: s2s_protocol_options: - no_sslv3 - cipher_server_preference - no_compression s2s_queue_type: ram | file The type of a queue for s2s packets. See description of queue_type op- tion for the explanation. The default value is the value defined in queue_type or ram if the latter is not set. s2s_timeout: timeout() A time to wait before closing an idle s2s connection. The default value is 1 hour. s2s_tls_compression: true | false Whether to enable or disable TLS compression for s2s connections. The default value is false. s2s_use_starttls: true | false | optional | required Whether to use STARTTLS for s2s connections. The value of false means STARTTLS is prohibited. The value of true or optional means STARTTLS is enabled but plain connections are still allowed. And the value of re- quired means that only STARTTLS connections are allowed. The default value is false (for historical reasons). s2s_zlib: true | false Whether to use zlib compression (as defined in XEP-0138) or not. The default value is false. WARNING: this type of compression is nowadays considered insecure. shaper: {ShaperName: Rate} The option defines a set of ../configuration/basic.md#shapers|shapers. Every shaper is assigned a name ShaperName that can be used in other parts of the configuration file, such as shaper_rules option. The shaper itself is defined by its Rate, where Rate stands for the maximum allowed incoming rate in bytes per second. When a connection exceeds this limit, ejabberd stops reading from the socket until the average rate is again below the allowed maximum. In the example below shaper normal limits the traffic speed to 1,000 bytes/sec and shaper fast lim- its the traffic speed to 50,000 bytes/sec: Example: shaper: normal: 1000 fast: 50000 shaper_rules: {ShaperRuleName: {Number|ShaperName: ACLName|ACLDefinition}} This option defines ../configuration/basic.md#shaper-rules|shaper rules to use for matching user/hosts. Semantics is similar to access_rules option, the only difference is that instead using allow or deny, a name of a shaper (defined in shaper option) or a positive number should be used. Example: shaper_rules: connections_limit: 10: user: peter@example.com 100: admin 5: all download_speed: fast: admin slow: anonymous_users normal: all log_days: 30 sm_cache_life_time: timeout() Same as cache_life_time, but applied to client sessions table cache only. If not set, the value from cache_life_time will be used. sm_cache_missed: true | false Same as cache_missed, but applied to client sessions table cache only. If not set, the value from cache_missed will be used. sm_cache_size: pos_integer() | infinity Same as cache_size, but applied to client sessions table cache only. If not set, the value from cache_size will be used. sm_db_type: mnesia | redis | sql Database backend to use for client sessions information. The default value is picked from default_ram_db option, or if it's not set, mnesia will be used. sm_use_cache: true | false Same as use_cache, but applied to client sessions table cache only. If not set, the value from use_cache will be used. sql_connect_timeout: timeout() A time to wait for connection to an SQL server to be established. The default value is 5 seconds. sql_database: DatabaseName | PathSqliteFile Note about this option: improved in 26.04. An SQL database name, being the default value ejabberd. If option sql_type is set to sqlite, this must be a full path to a database file, being the default value: '"@DATABASE_PATH@/sqlite/@HOST@.sqlite" sql_flags: [mysql_alternative_upsert] Note about this option: added in 24.02. This option accepts a list of SQL flags, and is empty by default. mysql_alternative_upsert forces the alternative upsert implementation in MySQL. sql_keepalive_interval: timeout() An interval to make a dummy SQL request to keep alive the connections to the database. There is no default value, so no keepalive requests are made. sql_odbc_driver: Path Note about this option: added in 20.12. Path to the ODBC driver to use to connect to a Microsoft SQL Server database. This option only applies if the sql_type option is set to mssql and sql_server is not an ODBC connection string. The default value is: libtdsodbc.so sql_password: Password The password for SQL authentication. The default is empty string. sql_pool_size: Size Number of connections to the SQL server that ejabberd will open for each virtual host. The default value is 10. WARNING: for SQLite this value is 1 by default and it's not recommended to change it due to po- tential race conditions. sql_port: 1..65535 The port where the SQL server is accepting connections. The default is 3306 for MySQL, 5432 for PostgreSQL and 1433 for MS SQL. The option has no effect for SQLite. sql_prepared_statements: true | false Note about this option: added in 20.01. This option is true by default, and is useful to disable prepared statements. The option is valid for PostgreSQL and MySQL. sql_query_timeout: timeout() A time to wait for an SQL query response. The default value is 60 sec- onds. sql_queue_type: ram | file The type of a request queue for the SQL server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set. sql_schema_multihost: true | false Note about this option: renamed in 25.10. Whether to use the data- base.md#singlehost-or-multihost|multihost SQL schema. All schemas are located at https://github.com/processone/ejabberd/tree/26.07/sql. There are two schemas available. The legacy singlehost schema stores one XMPP domain into one ejabberd database. The multihost schema can handle sev- eral XMPP domains in a single ejabberd database. The multihost schema is preferable when serving several XMPP domains and/or changing domains from time to time. This avoid need to manage several databases and han- dle complex configuration changes. The default depends on ../../ad- min/install/source.md#configure|./configure flag --en- able-sql-schema-multihost which is set at compile time. sql_server: Host | IP Address | ODBC Connection String | Unix Socket Path Note about this option: improved in 24.06. The hostname or IP address of the SQL server. For sql_type mssql or odbc this can also be an ODBC connection string. When sql_type is mysql or pgsql, this can be the path to a unix domain socket expressed like: "unix:/path/to/socket".The default value is localhost. sql_ssl: true | false Note about this option: improved in 20.03. Whether to use SSL encrypted connections to the SQL server. The option is only available for MySQL, MS SQL and PostgreSQL. The default value is false. sql_ssl_cafile: Path A path to a file with CA root certificates that will be used to verify SQL connections. Implies sql_ssl and sql_ssl_verify options are set to true. There is no default which means certificate verification is dis- abled. This option has no effect for MS SQL. sql_ssl_certfile: Path A path to a certificate file that will be used for SSL connections to the SQL server. Implies sql_ssl option is set to true. There is no de- fault which means ejabberd won't provide a client certificate to the SQL server. This option has no effect for MS SQL. sql_ssl_verify: true | false Whether to verify SSL connection to the SQL server against CA root cer- tificates defined in sql_ssl_cafile option. Implies sql_ssl option is set to true. This option has no effect for MS SQL. The default value is false. sql_start_interval: timeout() A time to wait before retrying to restore failed SQL connection. The default value is 30 seconds. sql_type: mssql | mysql | odbc | pgsql | sqlite The type of an SQL connection. The default is odbc. sql_username: Username A user name for SQL authentication. The default value is ejabberd. trusted_proxies: all | [Network1, Network2, ...] Specify what proxies are trusted when an HTTP request contains the header X-Forwarded-For. You can specify all to allow all proxies, or specify a list of IPs, possibly with masks. The default value is an empty list. Using this option you can know the real IP of the request, for admin purpose, or security configuration (for example using mod_fail2ban). IMPORTANT: The proxy MUST be configured to set the X-Forwarded-For header if you enable this option as, otherwise, the client can set it itself and as a result the IP value cannot be trusted for security rules in ejabberd. update_sql_schema: true | false Note about this option: updated in 24.06. Allow ejabberd to update SQL schema in MySQL, PostgreSQL and SQLite databases. This option was added in ejabberd 23.10, and enabled by default since 24.06. The default value is true. update_sql_schema_timeout: timeout() Note about this option: added in 24.07. Time allocated to SQL schema update queries. The default value is set to 5 minutes. use_cache: true | false Enable or disable cache. The default is true. Several modules have a similar option; and some core ejabberd parts support similar options too, see auth_use_cache, oauth_use_cache, router_use_cache, and sm_use_cache. validate_stream: true | false Whether to validate any incoming XML packet according to the schemas of supported XMPP extensions. WARNING: the validation is only intended for the use by client developers - don't enable it in production environ- ment. The default value is false. version: string() The option can be used to set custom ejabberd version, that will be used by different parts of ejabberd, for example by mod_version module. The default value is obtained at compile time from the underlying ver- sion control system. websocket_origin: ignore | URL This option enables validation for Origin header to protect against connections from other domains than given in the configuration file. In this way, the lower layer load balancer can be chosen for a specific ejabberd implementation while still providing a secure WebSocket con- nection. The default value is ignore. An example value of the URL is "https://test.example.org:8081". websocket_ping_interval: timeout() Defines time between pings sent by the server to a client (WebSocket level protocol pings are used for this) to keep a connection active. If the client doesn't respond to two consecutive pings, the connection will be assumed as closed. The value of 0 can be used to disable the feature. This option makes the server sending pings only for connec- tions using the RFC compliant protocol. For older style connections the server expects that whitespace pings would be used for this purpose. The default value is 60 seconds. websocket_timeout: timeout() Amount of time without any communication after which the connection would be closed. The default value is 300 seconds. MODULES This section describes modules options of ejabberd 26.07. The modules that changed in this version are marked with dh . mod_adhoc def:ad-hoc command : Command that can be executed by an XMPP client using XEP-0050. This module implements XEP-0050: Ad-Hoc Commands. It's an auxiliary module and is only needed by some of the other modules. Available options: report_commands_node: true | false Provide the Commands item in the Service Discovery. Default value: false. mod_adhoc_api Note about this option: added in 25.03. Execute (def:API commands) in a XMPP client using XEP-0050: Ad-Hoc Com- mands. This module requires mod_adhoc (to execute the commands), and recom- mends mod_disco (to discover the commands). Available options: default_version: integer() | string() What API version to use. If setting an ejabberd version, it will use the latest API version that was available in that (def:c2s) ejabberd version. For example, setting "24.06" in this option im- plies 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 ac- count from the server. It also changes their password to a randomly gener- ated 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 exam- ple below. The module has no options. Examples: With this configuration, vCards can only be modified with mod_admin_ex- tra 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@ex- ample.org will be kicked, and its password will be set to something like BANNED_ACCOUNT--20080425T21:45:07--2176635--Spammed_rooms ejabberdctl vhost example.org ban_account boby "Spammed rooms" Call to srg_create API using double-quotes and single-quotes: ejabberdctl srg_create g1 example.org "'Group number 1'" this_is_g1 g1 API Tags: ../../developer/ejabberd-api/admin-tags.md#accounts|accounts, ../../developer/ejabberd-api/admin-tags.md#erlang|erlang, ../../devel- oper/ejabberd-api/admin-tags.md#last|last, ../../developer/ejab- berd-api/admin-tags.md#private|private, ../../developer/ejab- berd-api/admin-tags.md#purge|purge, ../../developer/ejabberd-api/ad- min-tags.md#roster|roster, ../../developer/ejabberd-api/ad- min-tags.md#session|session, ../../developer/ejabberd-api/ad- min-tags.md#shared_roster_group|shared_roster_group, ../../devel- oper/ejabberd-api/admin-tags.md#stanza|stanza, ../../developer/ejab- berd-api/admin-tags.md#statistics|statistics, ../../developer/ejab- berd-api/admin-tags.md#vcard|vcard mod_admin_update_sql This module can be used to convert your existing SQL database from the sin- glehost to the multihost schema. Check the section database.md#single- host-or-multihost|Singlehost or Multihost for details. Please note that only MS SQL, MySQL, and PostgreSQL are supported. When the module is loaded use update_sql API. The module has no options. mod_announce This module enables configured users to broadcast announcements and to set the message of the day (MOTD). Configured users can perform these actions with an XMPP client either using Ad-Hoc Commands or sending messages to specific JIDs. Equivalent API commands are also available. Note This module can be resource intensive on large deployments as it may broadcast a lot of messages. This module should be disabled for in- stances 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 ejab- berd: * 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 mod- ule only. cache_missed: true | false Same as top-level cache_missed option, but applied to this module only. cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. use_cache: true | false Same as top-level use_cache option, but applied to this module only. API Tags: ../../developer/ejabberd-api/admin-tags.md#announce|announce mod_antispam Note about this option: added in 25.07. Filter spam messages and subscription requests received from remote servers based on Real-Time Block Lists (RTBL), lists of known spammer JIDs and/or URLs mentioned in spam messages. Traffic classified as spam is rejected with an error (and an [info] message is logged) unless the sender is sub- scribed 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 veri- fication. 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 vir- tual 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. Fur- thermore, 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 avail- able 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_ser- vices) then this domain will be ignored and stanzas from there won't be blocked. Use an absolute path, or the @CONFIG_PATH@ prede- fined keyword if the file is available in the configuration direc- tory. The default value is none. Example: modules: mod_antispam: rtbl_services: - xmppbl.org spam_jids_file: "@CONFIG_PATH@/spam_jids.txt" spam_dump_file: "@LOG_PATH@/spam/host-@HOST@.log" mod_auth_fast dh Note about this option: improved in 26.07. The module adds support for XEP-0484: Fast Authentication Streamlining To- kens that allows users to authenticate using self-managed tokens. Available options: db_type dh : mnesia | sql Note about this option: improved in 26.07. Same as top-level de- fault_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 re- fresh. 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 con- verted to format in To. The value of From can also be default, which is match-all rule. NOTE: the list of supported formats is de- tected 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 en- tity. 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 al- low_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 mes- sages from any user of this server are accepted even if no sub- scription 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 ba- sic.md#captcha|CAPTCHA of the Configuration Guide. The default value is false. drop: true | false This option specifies if strangers messages should be dropped or not. The default value is true. log: true | false This option specifies if strangers' messages should be logged (as info message) in ejabberd.log. The default value is false. mod_blocking The module implements XEP-0191: Blocking Command. This module depends on mod_privacy where all the configuration is per- formed. 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 mod- ule 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 sec- onds) 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 mod- ule 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 mes- sages 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 in- dicates 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 inac- tivity. The default value is true. queue_pep: true | false Queue PEP notifications while a client is inactive. When the queue is flushed, only the most recent notification of a given PEP node is delivered. The default value is true. queue_presence: true | false While a client is inactive, queue presence stanzas that indicate (un)availability. The default value is true. mod_configure Note about this option: improved in 25.10. The module provides server configuration functionalities using XEP-0030: Service Discovery and XEP-0050: Ad-Hoc Commands: * List and discover outgoing s2s, online client sessions and all regis- tered 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 Note about this option: added in 25.03. This option defines which access rule will be used to control who is allowed to access the features provided by this module. The default value is configure. Example: acl: admin: user: sun@localhost access_rules: configure: allow: admin modules: mod_configure: access: configure mod_conversejs Note about this option: improved in 25.07. This module serves a simple page for the Converse XMPP web browser client. To use this module, in addition to adding it to the modules section, you must also enable it in listen a ejabberd_http a listen-options.md#re- quest_handlers|request_handlers. Make sure either mod_bosh or listen.md#ejabberd_http_ws|ejabberd_http_ws are enabled in at least one request_handlers. When conversejs_css and conversejs_script are auto, by default they point to the public Converse client. When this module is enabled in modules, it adds automatically a request handler and link in WebAdmin. . This module is available since ejabberd 21.12. Available options: bosh_service_url: auto | BoshURL BOSH service URL to which Converse can connect to. The keyword @HOST@ is replaced with the real virtual host name. If set to auto, it will build the URL of the first configured BOSH request handler. The default value is auto. conversejs_css: auto | URL Converse CSS URL. The keyword @HOST@ is replaced with the hostname. The default value is auto. conversejs_options: {Name: Value} Note about this option: added in 22.05. Specify additional options to be passed to Converse. See Converse configuration. Only boolean, integer and string values are supported; lists are not supported. conversejs_plugins: [Filename] List of additional local files to include as scripts in the home- page. Please make sure those files are available in the path speci- fied in conversejs_resources option, in subdirectory plugins/. No- tice that libsignal is only required for OMEMO encryption in Con- verse 13 or lower; Converse 14 uses and includes libomemo. If using the public Converse client, then "libsignal" gets replaced with the URL of the public library. The default value is []. conversejs_resources: Path Note about this option: added in 22.05. Local path to the Converse files. If not set, the public Converse client will be used instead. conversejs_script: auto | URL Converse main script URL. The keyword @HOST@ is replaced with the hostname. The default value is auto. default_domain: Domain Specify a domain to act as the default for user JIDs. The keyword @HOST@ is replaced with the hostname. The default value is @HOST@. websocket_url: auto | WebSocketURL A WebSocket URL to which Converse can connect to. The @HOST@ key- word is replaced with the real virtual host name. If set to auto, it will build the URL of the first configured WebSocket request handler. The default value is auto. Examples: Manually setup WebSocket url, and use the public Converse client: listen: - port: 5280 module: ejabberd_http request_handlers: /bosh: mod_bosh /websocket: ejabberd_http_ws /conversejs: mod_conversejs modules: mod_bosh: {} mod_conversejs: websocket_url: "ws://@HOST@:5280/websocket" Host Converse locally and let auto detection of WebSocket and Converse URLs: listen: - port: 443 module: ejabberd_http tls: true request_handlers: /websocket: ejabberd_http_ws /conversejs: mod_conversejs modules: mod_conversejs: conversejs_resources: "/home/ejabberd/conversejs-x.y.z/package/dist" conversejs_plugins: ["libsignal-protocol.min.js"] # File path is: /home/ejabberd/conversejs-x.y.z/package/dist/plugins/libsignal-protocol.min.js Configure some additional options for Converse modules: mod_conversejs: websocket_url: auto conversejs_options: auto_away: 30 clear_cache_on_logout: true i18n: "pt" locked_domain: "@HOST@" message_archiving: always theme: dracula mod_delegation This module is an implementation of XEP-0355: Namespace Delegation. Only admin mode has been implemented by now. Namespace delegation allows exter- nal services to handle IQ using specific namespace. This may be applied for external PEP service. Warning Security issue: Namespace delegation gives components access to sensi- tive 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 sep- arately. 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-pub- sub.example.org component perform correctly disable the mod_pubsub mod- ule. 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 ser- vices 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 au- thentication failures are detected. Unlike the standalone program, mod_fail2ban clears the record of authenti- cation 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. ejab- berd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer. You can lock all your user base out of ejabberd when using this module behind a proxy. Available options: access: AccessName Specify an access rule for whitelisting IP addresses or networks. If the rule returns allow for a given IP address, that address will never be banned. The AccessName should be of type ip. The default value is none. c2s_auth_ban_lifetime: timeout() The lifetime of the IP ban caused by too many C2S authentication failures. The default value is 1 hour. c2s_max_auth_failures: Number The number of C2S authentication failures to trigger the IP ban. The default value is 20. API Tags: ../../developer/ejabberd-api/admin-tags.md#accounts|accounts mod_host_meta Note about this option: added in 22.05. This module serves small host-meta files as described in XEP-0156: Discov- ering Alternative XMPP Connection Methods. To use this module, in addition to adding it to the modules section, you must also enable it in listen a ejabberd_http a listen-options.md#re- quest_handlers|request_handlers. Notice it only works if listen.md#ejabberd_http|ejabberd_http has lis- ten-options.md#tls|tls enabled. Available options: bosh_service_url: undefined | auto | BoshURL BOSH service URL to announce. The keyword @HOST@ is replaced with the real virtual host name. If set to auto, it will build the URL of the first configured BOSH request handler. The default value is auto. websocket_url: undefined | auto | WebSocketURL WebSocket URL to announce. The keyword @HOST@ is replaced with the real virtual host name. If set to auto, it will build the URL of the first configured WebSocket request handler. The default value is auto. Example: listen: - port: 443 module: ejabberd_http tls: true request_handlers: /bosh: mod_bosh /websocket: ejabberd_http_ws /.well-known/host-meta: mod_host_meta /.well-known/host-meta.json: mod_host_meta modules: mod_bosh: {} mod_host_meta: bosh_service_url: "https://@HOST@:5443/bosh" websocket_url: "wss://@HOST@:5443/websocket" mod_http_api This module provides a ReST interface to call ../../developer/ejab- berd-api/index.md|ejabberd API commands using JSON data. To use this module, in addition to adding it to the modules section, you must also enable it in listen a ejabberd_http a listen-options.md#re- quest_handlers|request_handlers. To use a specific API version N, when defining the URL path in the re- quest_handlers, add a vN. For example: /api/v2: mod_http_api. To run a command, send a POST request to the corresponding URL: http://lo- calhost:5280/api/COMMAND-NAME Available options: default_version: integer() | string() Note about this option: added in 24.12. What API version to use when none is specified in the URL path. If setting an ejabberd ver- sion, it will use the latest API version that was available in that ejabberd version. For example, setting "24.06" in this option im- plies 2. The default value is the latest version. Example: listen: - port: 5280 module: ejabberd_http request_handlers: /api: mod_http_api modules: mod_http_api: default_version: 2 mod_http_fileserver Note about this option: improved docroot in 26.01. This simple module serves files from the local disk over HTTP. Available options: accesslog: Path File to log accesses using an Apache-like format. No log will be recorded if this option is not specified. content_types: {Extension: Type} Specify mappings of extension to content type. There are several content types already defined. With this option you can add new de- finitions or modify existing ones. The default values are: Example: content_types: .avi: video/avi .bmp: image/bmp .bz2: application/x-bzip2 .css: text/css .gif: image/gif .gz: application/x-gzip .html: text/html .ico: image/vnd.microsoft.icon .jar: application/java-archive .jpeg: image/jpeg .jpg: image/jpeg .js: text/javascript .json: application/json .m4a: audio/mp4 .map: application/json .mp3: audio/mpeg .mp4: video/mp4 .mpeg: video/mpeg .mpg: video/mpeg .ogg: application/ogg .pdf: application/pdf .png: image/png .rtf: application/rtf .svg: image/svg+xml .tiff: image/tiff .ttf: font/ttf .txt: text/plain .wav: audio/wav .wasm: application/wasm .webp: image/webp .woff: font/woff .woff2: font/woff2 .xml: application/xml .xpi: application/x-xpinstall .xul: application/vnd.mozilla.xul+xml .xz: application/x-xz .zip: application/zip custom_headers: {Name: Value} Indicate custom HTTP headers to be included in all responses. There are no custom headers by default. default_content_type: Type Specify the content type to use for unknown extensions. The default value is application/octet-stream. directory_indices: [Index, ...] Indicate one or more directory index files, similarly to Apache's DirectoryIndex variable. When an HTTP request hits a directory in- stead of a regular file, those directory indices are looked in or- der, and the first one found is returned. The default value is an empty list. docroot: PathDir | {PathURL, PathDir} Note about this option: improved in 26.01. Directory to serve the files from, or a map with several URL path (as specified in lis- ten-options.md#request_handlers|request_handlers) and their corre- sponding 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 direc- tory /var/www in the address http://example.org:5280/pub/content/. In this example a new content type ogg is defined, png is redefined, and jpg definition is deleted: listen: - port: 5280 module: ejabberd_http request_handlers: /pub/content: mod_http_fileserver modules: mod_http_fileserver: docroot: /var/www accesslog: /var/log/ejabberd/access.log directory_indices: - index.html - main.htm custom_headers: X-Powered-By: Erlang/OTP X-Fry: "It's a widely-believed fact!" content_types: .ogg: audio/ogg .png: image/png default_content_type: text/html mod_http_upload Note about this option: added content_types in 26.01. This module allows for requesting permissions to upload a file via HTTP as described in XEP-0363: HTTP File Upload. If the request is accepted, the client receives a URL for uploading the file and another URL from which that file can later be downloaded. In order to use this module, it must be enabled in listen a ejabberd_http a listen-options.md#request_handlers|request_handlers. Available options: access: AccessName This option defines the access rule to limit who is permitted to use the HTTP upload service. The default value is local. If no ac- cess rule of that name exists, no user will be allowed to use the service. append_module_config dh : {UploadHost: Options} Note about this option: added in 26.07. Add a few specific options to a certain upload host previously defined in the mod_http_upload hosts option. Right now only name and vcard can be defined here. This is similar to the toplevel append_host_config option, but in this case it's applied to this module options. Example: modules: mod_http_upload: hosts: - service1.@HOST@ - service2.@HOST@ name: "Service General" append_module_config: service1.localhost: name: "Service 1" service2.example.net: name: "Service 2" content_types: {Extension: Type} Note about this option: added in 26.01. Specify mappings of exten- sion 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 spec- ified as an octal number (see the chmod(1) manual page) within dou- ble 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 ab- solute 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@/up- load". 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 unde- fined, 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 op- tion 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 gen- erated 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 charac- ters. 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 con- structed from an XML representation of vCard. Since the representa- tion 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 num- ber 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 spec- ified 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 num- ber of megabytes for any JID that is supposed to have a quota limit. See the description of the access_hard_quota option for de- tails. The default value is soft_upload_quota. max_days: Days If a number larger than zero is specified, any files (and directo- ries) older than this number of days are removed from the subdirec- tories 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 ac- cess_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 dh Note about this option: improved in 26.07. Allow User Invitation and Account Creation to create out-of-band links to onboard others onto the XMPP network and establish a mutual subscription. This implements XEP-0379: Pre-Authenticated Roster Subscription, XEP-0401: Ad-hoc Account Invitation Generation, and XEP-0445: Pre-Authenticated In-Band Registration. These invitations are created as XMPP URIs either via ad-hoc commands or via API commands (like generate_invite API and generate_invite_with_user- name API), are then meant to be sent out-of-band. The receiving user should have installed a client that supports those invi- tations. 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 land- ing_page to either auto or an URL template like https://{{ host }}/in- vites/{{ invite.token }} if your server setup includes a so called reverse proxy. Furthermore you need to connect this module as a handler of an ejab- berd_http listener as shown at the example below. For convenience there's now also a start page included at wherever you mount mod_invites at the ejabberd_http handler. This start page will allow people to generate invites by giving their username and password. As such the URL should be protected by HTTPS. The main use-case is when people have only clients, that don't support generating invites natively. If you'd rather want to use an external service, set landing_page to some- thing like http://{{ host }}:8080/easy-xmpp-invites/#{{ in- vite.uri|strip_protocol }} or https://invites.joinjabber.org/#{{ in- vite.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 in- vite.uri, there are also filters defined, most notably strip_proto- col. Here's an example: http://{{ host }}:8080/easy-xmpp-in- vites/#{{ 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 Laun- drette". Used in landing page templates. templates_dir: Path The directory containing templates and static files used for land- ing page and web registration form. Only needs to be set if you want to ship your own set of templates or list of recommended apps. token_expire_seconds: pos_integer() Number of seconds until token expires. Default value is 432000 (that is five days: 5 * 24 * 60 * 60) webchat_url: none | auto | Webchat URL Note about this option: added in 26.03. URL to a webchat client. Upon manual registration through web-form this will be recommended in order to get started. If auto is chosen, we pick the mod_con- versejs 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 dis- able regular in-band registration, you would have a config like this: acl: admin: - user: "my_admin_user@example.com" access_rules: register: allow: admin modules: mod_invites: landing_page: auto mod_register: allow_modules: - mod_invites If you want all your users to be able to send create account invites, you would configure your server like this instead. Note that the names of the access rules are just examples and you're free to change them. acl: local: user_regexp: "" access_rules: create_account_invite: allow: local modules: mod_invites: access_create_account: create_account_invite landing_page: auto mod_register: allow_modules: - mod_invites mod_jidprep This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format. This might be useful for clients in certain constrained environments, or for testing purposes. Available options: access: AccessName This option defines which access rule will be used to control who is allowed to use this service. The default value is local. mod_last This module adds support for XEP-0012: Last Activity. It can be used to discover when a disconnected user last accessed the server, to know when a connected user was last active on the server, or to query the uptime of the ejabberd server. Available options: cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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 recom- mended. 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 prefer- ences. The default value is all. archive_muc_as_mucsub: true | false Note about this option: added in 25.10. When this option is enabled incoming groupchat messages for users that have mucsub subscription to a room from which message originated will have those messages archived after being converted to mucsub event messages.The default value is false. assume_mam_usage: true | false This option determines how ejabberd's stream management code (see mod_stream_mgmt) handles unacknowledged messages when the connec- tion 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 mod- ule 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 dis- ables 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 sep- arate mucsub message is stored. With this option enabled, when a user fetches archive virtual mucsub, messages are generated from muc archives. The default value is false. API Tags: ../../developer/ejabberd-api/admin-tags.md#mam|mam, ../../de- veloper/ejabberd-api/admin-tags.md#purge|purge mod_matrix_gw Note about this option: improved in 25.08. Matrix gateway. Supports room versions 9, 10 and 11 since ejabberd 25.03; room versions 4 and higher since ejabberd 25.07; room version 12 (hydra rooms) since ejabberd 25.08. Erlang/OTP 25 or higher is required to use this module. This module is available since ejabberd 24.02. Available options: host: Host This option defines the Jabber IDs of the service. If the host op- tion is not specified, the Jabber ID will be the hostname of the virtual host with the prefix "matrix.". The keyword @HOST@ is re- placed 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 gate- way 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 mes- sage 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 sup- ported). 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 in- coming connections/packets. The default value is 11111. mod_mix Note about this option: added in 16.03 and improved in 19.02. This module is an experimental implementation of XEP-0369: Mediated Infor- mation eXchange (MIX). It's asserted that the MIX protocol is going to re- place the MUC protocol in the future (see mod_muc). To learn more about how to use that feature, you can refer to our tutorial: ../../tutorials/mix-010.md|Getting started with MIX The module depends on mod_mam. Available options: access_create: AccessName An access rule to control MIX channels creations. The default value is all. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. host Deprecated. Use hosts instead. hosts: [Host, ...] This option defines the Jabber IDs of the service. If the hosts op- tion is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "mix.". The keyword @HOST@ is re- placed 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): Par- ticipant 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 mod- ule only. cache_missed: true | false Same as top-level cache_missed option, but applied to this module only. cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. use_cache: true | false Same as top-level use_cache option, but applied to this module only. mod_mqtt This module adds ../guide/mqtt/index.md|support for the MQTT protocol ver- sion 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 de- fault there are no restrictions. access_subscribe: {TopicFilter: AccessName} Access rules to restrict access to topics for subscribers. By de- fault there are no restrictions. cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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 resump- tion. 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 re- mote servers It can update topics on remote servers when local user updates local topic, or can subscribe for changes on remote server, and update lo- cal 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: user- name and password fields, or certfile pointing to client cer- tificate. Certificate authentication can be used only with mqtts, mqtt5s, wss, wss5. publish: {LocalTopic: RemoteTopic} Either publish or subscribe must be set, or both. subscribe: {RemoteTopic: LocalTopic} Either publish or subscribe must be set, or both. Example: modules: mod_mqtt_bridge: replication_user: "mqtt@xmpp.server.com" servers: "mqtt://server.com": authentication: certfile: "/etc/ejabberd/mqtt_server.pem" publish: "localA": "remoteA" # local changes to 'localA' will be replicated on remote server as 'remoteA' "topicB": "topicB" subscribe: "remoteB": "localB" # changes to 'remoteB' on remote server will be stored as 'localB' on local server mod_muc Note about this option: incorporated mod_muc_occupantid in 26.02. This module provides support for Multi-User Chat (MUC). Users can discover existing rooms, join or create them. Occupants of a room can chat in public or have private chats. Protocols implemented in this module: * 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 nick- name, 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 man- aging a set of rooms goes down, the rooms disappear and they will be recre- ated 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 de- fault value is all, which means everyone is allowed to modify that option. access_persistent: AccessName To configure who is allowed to modify the persistent room option. The default value is all, which means everyone is allowed to modify that option. access_register: AccessName Note about this option: improved in 23.10. This option specifies who is allowed to register nickname within the Multi-User Chat ser- vice and rooms. The default is all for backward compatibility, which means that any user is allowed to register any free nick in the MUC service and in the rooms. append_module_config dh : {MUCHost: Options} Note about this option: added in 26.07. Add a few specific options to a certain MUC host previously defined in the mod_muc hosts op- tion. This is similar to the toplevel append_host_config option, but in this case it's applied to the mod_muc options. Example: modules: mod_muc: hosts: - service1.@HOST@ - service2.@HOST@ name: "Service General" append_module_config: service1.localhost: name: "Service 1" service2.example.net: name: "Service 2" cleanup_affiliations_on_start: true | false Note about this option: added in 22.05. Remove affiliations for non-existing local users on startup. The default value is false. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. default_room_options: Options Define the default room options. Note that the creator of a room can modify the options of his room at any time using an XMPP client with MUC capability. The Options are: allow_change_subj: true | false Allow occupants to change the subject. The default value is true. allow_private_messages_from_visitors: anyone | moderators | nobody Visitors can send private messages to other occupants. The de- fault value is anyone which means visitors can send private messages to any occupant. allow_query_users: true | false Occupants can send IQ queries to other occupants. The default value is true. allow_subscription: true | false Allow users to subscribe to room events as described in ../../developer/xmpp-clients-bots/exten- sions/muc-sub.md|Multi-User Chat Subscriptions. The default value is false. allow_user_invites: true | false Allow occupants to send invitations. The default value is false. allow_visitor_nickchange: true | false Allow visitors to change nickname. The default value is true. allow_visitor_status: true | false Allow visitors to send status text in presence updates. If dis- allowed, 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 de- fault value is true. allowpm: anyone | participants | moderators | none Who can send private messages. The default value is anyone. anonymous: true | false The room is anonymous: occupants don't see the real JIDs of other occupants. Note that the room moderators can always see the real JIDs of the occupants. The default value is true. captcha_protected: true | false When a user tries to join a room where they have no affiliation (not owner, admin or member), the room requires them to fill a CAPTCHA challenge (see section basic.md#captcha|CAPTCHA in or- der to accept their join in the room. The default value is false. description: Room Description Short description of the room. The default value is an empty string. enable_hats: true | false Note about this option: improved in 25.10. Allow extended roles as defined in XEP-0317: Hats. For ejabberd older than 25.10 see the ../../tutorials/muc-hats.md|MUC Hats page. The default value is true. lang: Language Preferred language for the discussions in the room. The lan- guage 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 de- fault 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 de- fault 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 de- fault 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 op- tion.The default value is an empty string. vcard_xupdate: undefined | external | AvatarHash Set the hash of the avatar image. The default value is unde- fined. voice_request_min_interval: Number Minimum interval between voice requests, in seconds. The de- fault 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 ser- vice. 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 op- tion is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "conference.". The keyword @HOST@ is replaced with the real virtual host name. max_captcha_whitelist: Number Note about this option: added in 21.01. This option defines the maximum number of characters that Captcha Whitelist can have when configuring the room. The default value is infinity. max_password: Number Note about this option: added in 21.01. This option defines the maximum number of characters that Password can have when configur- ing the room. The default value is infinity. max_room_desc: Number This option defines the maximum number of characters that Room De- scription 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 configura- tion 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 al- lowed to enter the room when the maximum number of allowed occu- pants was reached. The default limit is 5. max_users_presence: Number This option defines after how many users in the room, it is consid- ered overcrowded. When a MUC room is considered overcrowded, pres- ence 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 de- fined, message rate is not limited. This feature can be used to protect a MUC service from occupant abuses and limit number of mes- sages 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 mes- sage 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 broad- casted to all occupants in the room after expiration of the inter- val 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 dis- abled, the room is only loaded on first participant join. The de- fault 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 sat- isfy 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 con- structed from an XML representation of vCard. Since the representa- tion 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 Note about this option: added in 22.05. How many users can be sub- scribed to a room at once using the subscribe_room_many API. The default value is 50. API Tags: ../../developer/ejabberd-api/admin-tags.md#muc|muc, ../../de- veloper/ejabberd-api/admin-tags.md#muc_room|muc_room, ../../devel- oper/ejabberd-api/admin-tags.md#muc_sub|muc_sub mod_muc_log This module enables optional logging of Multi-User Chat (MUC) public con- versations to HTML. Once you enable this module, users can join a room us- ing 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 dis- played, 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 dis- able 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 op- tion. 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 sub- dirs. 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 be- low: 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 op- erating 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 con- ference. The conference name is appended to the URL if dirname op- tion is set to room_name or a conference JID is appended to the URL otherwise. There is no default value. mod_muc_rtbl Note about this option: added in 23.04. This module implement Real-time blocklists for MUC rooms. It works by observing remote pubsub node conforming with specification de- scribed 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 op- tion is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "multicast.". The keyword @HOST@ is replaced with the real virtual host name. Please note: this mod- ule only uses the first vhost defined in this option. limits: Sender: Stanza: Number Specify a list of custom limits which override the default ones de- fined 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 Mes- sages 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_mes- sages. 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 of- fline. It will reduce chat room load, without any drawback in stan- dard use cases. You may change default value only if you have a custom module which uses offline hook after mod_offline. This op- tion 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 de- fault value is false, meaning the optimization is enabled. cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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 mes- sages, 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: ../../developer/ejabberd-api/admin-tags.md#offline|offline mod_ping This module implements support for XEP-0199: XMPP Ping and periodic keepalives. When this module is enabled ejabberd responds correctly to ping requests, as defined by the protocol. Available options: ping_ack_timeout: timeout() How long to wait before deeming that a client has not answered a given server ping request. NOTE: when mod_stream_mgmt is loaded and stream management is enabled by a client, this value is ignored, and the ack_timeout applies instead. The default value is unde- fined. 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_in- terval 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 en- abled by a client, killing the client connection doesn't mean killing the client session - the session will be kept alive in or- der 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 ex- ceeding stanzas are silently dropped, and a warning is logged. Available options: count: Number The number of subscription presence stanzas (subscribe, unsub- scribe, 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 mod- ule 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, re- trieve 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 con- ferences (XEP-0048: Bookmarks). It also implements the bookmark conversion described in XEP-0402: PEP Na- tive Bookmarks, see bookmarks_to_pep API. Available options: cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule only. cache_missed: true | false Same as top-level cache_missed option, but applied to this module only. cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. use_cache: true | false Same as top-level use_cache option, but applied to this module only. API Tags: ../../developer/ejabberd-api/admin-tags.md#private|private mod_privilege Note about this option: improved in 24.10. This module is an implementation of XEP-0356: Privileged Entity. This ex- tension 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 pow- erful 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 permis- sions 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 per- missions are given. The Options are: managed_entity: AccessName An access rule that gives permissions to the component to re- ceive server presences. The default value is none. roster: AccessName An access rule that gives permissions to the component to re- ceive 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 Note about this option: 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 a ejabberd_http a listen-options.md#re- quest_handlers|request_handlers. Notice you should set in listen.md#ejab- berd_http|ejabberd_http the option listen-options.md#tls|tls enabled. Available options: alternativeJids: [string()] List of JIDs (XMPP server domains) a provider offers for registra- tion 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 other- wise. 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). Atten- tion: 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 pass- word reset (e.g., via email) or describing how to manually reset a password (e.g., by contacting the provider). The keyword @LAN- GUAGE_URL@ is replaced with each language. The default value is an URL built automatically if mod_register_web is configured as a re- quest_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., cer- tificate 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. append_module_config: {ProxyHost: Options} Note about this option: added in 25.xx. Add a few specific options to a certain upload host previously defined in the mod_proxy65 hosts option. Right now only name and vcard can be defined here. This is similar to the toplevel append_host_config option, but in this case it's applied to this module options. Example: modules: mod_proxy65: hosts: - service1.@HOST@ - service2.@HOST@ name: "Service General" append_module_config: service1.localhost: name: "Service 1" service2.example.net: name: "Service 2" auth_type: anonymous | plain SOCKS5 authentication type. The default value is anonymous. If set to plain, ejabberd will use authentication backend as it would for SASL PLAIN. host Deprecated. Use hosts instead. hostname: Host Defines a hostname offered by the proxy when establishing a session with clients. This is useful when you run the proxy behind a NAT. The keyword @HOST@ is replaced with the virtual host name. The de- fault is to use the value of ip option. Examples: proxy.mydo- main.org, 200.150.100.50. hosts: [Host, ...] This option defines the Jabber IDs of the service. If the hosts op- tion 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 con- structed from an XML representation of vCard. Since the representa- tion 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 function- ality in mod_pubsub can be extended using plugins. The plugin that imple- ments PEP (XEP-0163: Personal Eventing via Pubsub) is enabled in the de- fault 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. append_module_config dh : {PubSubHost: Options} Note about this option: added in 26.07. Add a few specific options to a certain PubSub host previously defined in the mod_pubsub hosts option. Right now only name and vcard can be defined here. This is similar to the toplevel append_host_config option, but in this case it's applied to this module options. Example: modules: mod_pubsub: hosts: - service1.@HOST@ - service2.@HOST@ name: "Service General" append_module_config: service1.localhost: name: "Service 1" service2.example.net: name: "Service 2" db_type: mnesia | sql Same 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 op- tion 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 mem- ory usage, as every item is stored in memory. max_item_expire_node: timeout() | infinity Note about this option: 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. De- fault 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 pub- sub 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 de- fined 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 con- structed from an XML representation of vCard. Since the representa- tion 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: ../../developer/ejabberd-api/admin-tags.md#purge|purge mod_pubsub_serverinfo Note about this option: 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 de- fined 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 so- lution 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 mod- ule 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 spec- ified text will be included in place of the actual message body. This can be useful to signal the app server whether the notifica- tion was triggered by a message with body (as opposed to other types of traffic) without leaking actual message contents. The de- fault 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 Note about this option: 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: ../../developer/ejabberd-api/admin-tags.md#purge|purge mod_push_keepalive This module tries to keep the stream management session (see mod_stream_mgmt) of a disconnected mobile client alive if the client en- abled push notifications for that session. However, the normal session re- sumption 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 it- self. 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 Ac- cessName is none, then registering new accounts using In-Band Reg- istration 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 ac- counts from s2s or existing c2s sessions. You can change it by defining access rule in this option. Use with care: allowing regis- tration from s2s leads to uncontrolled massive accounts creation by rogue users. access_remove: AccessName Specify rules to restrict access for user unregistration. By de- fault any user is able to unregister their account. allow_modules: all | [Module, ...] Note about this option: added in 21.12. List of modules that can register accounts, or all. The default value is all, which is equivalent to something like [mod_register, mod_register_web]. captcha_protected: true | false Protect registrations with basic.md#captcha|CAPTCHA. The default is false. ip_access: AccessName Define rules to allow or deny account registration depending on the IP address of the XMPP client. The AccessName should be of type ip. The default value is all. password_strength: Entropy This option sets the minimum Shannon entropy for passwords. The value Entropy is a number of bits of entropy. The recommended mini- mum 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 ac- count. 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 basic.md#captcha|CAPTCHA to register a new account. To enable this feature, configure the top-level captcha_cmd and top-level captcha_url options. As an example usage, the users of the host localhost can visit the page: https://localhost:5280/register/ It is important to include the last / character in the URL, otherwise the subpages URL will be incorrect. This module is enabled in listen a ejabberd_http a listen-options.md#re- quest_handlers|request_handlers. There is no need to enable this module in modules, but it adds a link to the register page in WebAdmin menu. The module depends on mod_register where all the configuration is performed. The module has no options. Example: listen: - port: 5280 module: ejabberd_http request_handlers: /register: mod_register_web modules: mod_register: {} mod_roster This module implements roster management as defined in RFC6121 Section 2. The module also adds support for XEP-0237: Roster Versioning. Available options: access: AccessName This option can be configured to specify rules to restrict roster management. If the rule returns deny on the requested user name, that user cannot modify their personal roster, i.e. they cannot add/remove/modify contacts or send presence subscriptions. The de- fault value is all, i.e. no restrictions. cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule only. cache_missed: true | false Same as top-level cache_missed option, but applied to this module only. cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only. db_type: mnesia | sql Same as top-level default_db option, but applied to this module only. store_current_id: true | false If this option is set to true, the current roster version number is stored on the database. If set to false, the roster version number is calculated on the fly each time. Enabling this option reduces the load for both ejabberd and the database. This option does not affect the client in any way. This option is only useful if option versioning is set to true. The default value is false. IMPORTANT: if you use mod_shared_roster or mod_shared_roster_ldap, you must set the value of the option to false. use_cache: true | false Same as top-level use_cache option, but applied to this module only. versioning: true | false Enables/disables Roster Versioning. The default value is false. Example: modules: mod_roster: versioning: true store_current_id: false API Tags: ../../developer/ejabberd-api/admin-tags.md#roster|roster mod_s2s_bidi Note about this option: added in 24.10. The module adds support for XEP-0288: Bidirectional Server-to-Server Con- nections that allows using single s2s connection to communicate in both di- rections. 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 mod- ule is only recommended for backward compatibility with servers running outdated software or non-TLS servers, or those with invalid certifi- cates (as long as you accept the risks, e.g. you assume that the remote server has an invalid certificate due to poor administration and not because it's compromised). Available options: access: AccessName An access rule that can be used to restrict dialback for some servers. The default value is all. Example: modules: mod_s2s_dialback: access: allow: server: legacy.domain.tld server: invalid-cert.example.org deny: all mod_scram_upgrade Note about this option: added in 24.10. The module adds support for XEP-0480: SASL Upgrade Tasks that allows users to upgrade passwords to more secure representation. Available options: offered_upgrades: list(sha256, sha512) List with upgrade types that should be offered Example: modules: mod_scram_upgrade: offered_upgrades: - sha256 - sha512 mod_service_log This module forwards copies of all stanzas to remote XMPP servers or compo- nents. 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 manu- ally 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 re- place 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 regis- tered users in the virtual host; which is only recommended for a small server with just a few hundred users. The special member directive @on- line@ represents the online users in the virtual host. With those two directives, the actual list of members in those shared rosters is gen- erated 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 re- turn 503 errors. Available options: cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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: Manage- ment, Marketing and Sales. All group members should see all other mem- bers in their rosters. Additionally, all managers should have all mar- keting 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 unspeci- fied, 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 informa- tion. 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 at- tributes 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_va- lidity. These parameters control the behaviour of the module. * Connection parameters: The module also accepts the connection parame- ters, all of which default to the top-level parameter of the same name, if unspecified. See ldap.md#ldap-connection|LDAP Connection section for more information about them. Check also the ldap.md#ldap-examples|Configuration examples section to get details about retrieving the roster, and configuration examples including Flat DIT and Deep DIT. Available options: cache_life_time Same as top-level cache_life_time option, but applied to this mod- ule only. cache_missed Same as top-level cache_missed option, but applied to this module only. cache_size Same as top-level cache_size option, but applied to this module only. ldap_auth_check: true | false Whether the module should check (via the ejabberd authentication subsystem) for existence of each user in the shared LDAP roster. Set to false if you want to disable the check. Default value is true. ldap_backups Same as top-level ldap_backups option, but applied to this module only. ldap_base Same as top-level ldap_base option, but applied to this module only. ldap_deref_aliases Same as top-level ldap_deref_aliases option, but applied to this module only. ldap_encrypt Same as top-level ldap_encrypt option, but applied to this module only. ldap_filter Additional filter which is AND-ed together with "User Filter" and "Group Filter". For more information check the LDAP ldap.md#fil- ters|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 ob- jectClass you use for your group objects, for example: posixGroup a memberUid; groupOfNames a member; groupOfUniqueNames a uniqueMem- ber. ldap_memberattr_format A globbing format for extracting user ID from the value of the at- tribute named by ldap_memberattr. Defaults to %u, which means that the whole value is the member ID. If you change it to something different, you may also need to specify the User and Group Filters manually; see section Filters. ldap_memberattr_format_re A regex for extracting user ID from the value of the attribute named by ldap_memberattr. Check the LDAP ldap.md#control-parame- ters|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 ros- ter" 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 mod- ule only. ldap_ufilter "User Filter", used for retrieving the human-readable name of ros- ter entries (usually full names of people in the roster). See also the parameters ldap_userdesc and ldap_useruid. For more information check the LDAP ldap.md#filters|Filters section. ldap_uids Same as top-level ldap_uids option, but applied to this module only. ldap_userdesc The name of the attribute which holds the human-readable user name. Retrieved from results of the "User Filter". Defaults to cn. ldap_userjidattr The name of the attribute 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 ob- ject. 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 en- ables 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, further- more, 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 listen.md#ejabberd_sip|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 connec- tions. The default value is 2 minutes. flow_timeout_udp: timeout() The options sets a keep-alive timer for SIP outbound UDP connec- tions. The default value is 29 seconds. record_route: URI When the option always_record_route is set to true or when SIP out- bound is utilized, ejabberd inserts "Record-Route" header field with this URI into a SIP message. The default is a SIP URI con- structed 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 con- structed 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/to- tal). * Total number of registered users on all virtual hosts (users/all-hosts/total). * Total number of online users on the current virtual host (users/on- line). * Total number of online users on all virtual hosts (users/all-hosts/on- line). 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 al- lows active management of an XML stream between two XMPP entities, includ- ing 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 mod- ule 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 inte- gers 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 initia- tion. It should definitely be set higher that the size of the of- fline queue (for example at least 3 times the value of the max of- fline 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 ac- knowledged 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, un- acknowledged messages are resent only if no other resource is on- line when the session times out. Otherwise, error messages are gen- erated. resume_timeout: timeout() This option configures the (default) period of time until a session times out if the connection is lost. During this period of time, a client may resume its session. Note that the client may request a different timeout value, see the max_resume_timeout option. Setting it to 0 effectively disables session resumption. The default value is 5 minutes. mod_stun_disco Note about this option: added in 20.04. This module allows XMPP clients to discover STUN/TURN services and to ob- tain 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 ejab- berd's built-in TURN service is used, TURN relays allocated using temporary credentials will be terminated shortly after the creden- tials expired. The default value is 12 hours. Note that restarting the ejabberd node invalidates any temporary credentials offered be- fore 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 config- ured manually using the services option (see below). For non-anony- mous 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 op- tion 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 spec- ified explicitly, and must be shared with that service. This will only work with ejabberd's built-in STUN/TURN server and with exter- nal servers that support the same REST API For Access To TURN Ser- vices. Unless the offer_local_services is set to false, the explic- itly 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 ad- dress (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 de- fault port number is 3478 for non-TLS services and 5349 for TLS services. restricted: true | false This option determines whether temporary credentials for ac- cessing 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 re- trieve 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. append_module_config dh : {VcardHost: Options} Note about this option: added in 26.07. Add a few specific options to a certain upload host previously defined in the mod_vcard hosts option. Right now only name can be defined here. This is similar to the toplevel append_host_config option, but in this case it's ap- plied to this module options. Example: modules: mod_vcard: hosts: - service1.@HOST@ - service2.@HOST@ name: "Service General" append_module_config: service1.localhost: name: "Service 1" service2.example.net: name: "Service 2" cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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 op- tion is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "vjud.". The keyword @HOST@ is re- placed with the real virtual host name. matches: pos_integer() | infinity With this option, the number of reported search results can be lim- ited. 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 ig- nored 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 con- structed from an XML representation of vCard. Since the representa- tion 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 auto- matically 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 mod- ule 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 re- placed 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 au- tomatically the avatar hash on behalf of the client. So, the contacts re- ceive 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 gener- ated by ejabberd. By enabling this module, each vCard modification produces a hash recalcula- tion, and each presence sent by a client produces hash retrieval and a presence stanza rewrite. For this reason, enabling this module will intro- duce a computational overhead in servers with clients that change fre- quently 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 back- ward compatibility. Available options: cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this mod- ule 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. LISTENERS This section describes listeners options of ejabberd 26.07. TODO AUTHOR ProcessOne. VERSION This document describes the configuration file of ejabberd 26.07. Configu- ration options of other ejabberd versions may differ significantly. REPORTING BUGS Report bugs to https://github.com/processone/ejabberd/issues SEE ALSO Default configuration file: https://github.com/processone/ejab- berd/blob/26.07/ejabberd.yml.example Main site: https://ejabberd.im Documentation: https://docs.ejabberd.im Configuration Guide: https://docs.ejabberd.im/admin/configuration Source code: https://github.com/processone/ejabberd COPYING Copyright (c) 2002-2026 ProcessOne. 07/30/2026 EJABBERD.YML(5)
NAME | SYNOPSIS | DESCRIPTION | TOP LEVEL OPTIONS | MODULES | LISTENERS | AUTHOR | VERSION | REPORTING BUGS | SEE ALSO | COPYING
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ejabberd.yml&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>