table of contents
- buster-backports 21.01-2~bpo10+1
- testing 21.01-2
- unstable 21.01-2
EJABBERD.YML(5) | EJABBERD.YML(5) |
NAME¶
ejabberd.yml - main configuration file for ejabberd.SYNOPSIS¶
ejabberd.ymlDESCRIPTION¶
The configuration file is written in YAML language.Warning
YAML is indentation sensitive, so make sure you respect indentation, or otherwise you will get pretty cryptic configuration errors.
Logically, configuration options are split into 3 main categories: Modules, Listeners and everything else called Top Level options. Thus this document is split into 3 main chapters describing each category separately. So, the contents of ejabberd.yml will typically look like this:
hosts: - example.com - domain.tld loglevel: info ... listen: - port: 5222 module: ejabberd_c2s ... modules: mod_roster: {} ...
Any configuration error (such as syntax error, unknown option or invalid option value) is fatal in the sense that ejabberd will refuse to load the whole configuration file and will not start or will abort configuration reload.
All options can be changed in runtime by running ejabberdctl reload-config command. Configuration reload is atomic: either all options are accepted and applied simultaneously or the new configuration is refused without any impact on currently running configuration.
Some options can be specified for particular virtual host(s) only using host_config or append_host_config options. Such options are called local. Examples are modules, auth_method and default_db. The options that cannot be defined per virtual host are called global. Examples are loglevel, certfiles and listen. It is a configuration mistake to put global options under host_config or append_host_config section - ejabberd will refuse to load such configuration.
It is not recommended to write ejabberd.yml from scratch. Instead it is better to start from "default" configuration file available at https://github.com/processone/ejabberd/blob/21.01/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 21.01access_rules: {AccessName: {allow|deny: ACLRules|ACLName}}
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}}
ip: Network
node_glob: Pattern
node_regexp: user_regexp@server_regexp
resource: Resource
resource_glob: Pattern
resource_regexp: Regexp
server: Server
server_glob: Pattern
server_regexp: Regexp
user: Username
user_glob: Pattern
user_regexp: Regexp
acme: Options
auto: true | false
ca_url: URL
cert_type: rsa | ec
contact: [Contact, ...]
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
allow_multiple_connections: true | false
anonymous_protocol: login_anon | sasl_anon | both
api_permissions: [Permission, ...]
append_host_config: {Host: Options}
auth_cache_life_time: timeout()
auth_cache_missed: true | false
auth_cache_size: pos_integer() | infinity
auth_method: [mnesia | sql | anonymous | external | jwt | ldap | pam, ...]
auth_opts: [Option, ...]
auth_password_format: plain | scram
auth_scram_hash: sha | sha256 | sha512
auth_use_cache: true | false
c2s_cafile: Path
You can use host_config to specify this option per-vhost.
To set a specific file per listener, use the listener’s cafile option. Please notice that c2s_cafile overrides the listener’s cafile option.
c2s_ciphers: [Cipher, ...]
Example:
c2s_ciphers: - HIGH - "!aNULL" - "!eNULL" - "!3DES" - "@STRENGTH"
c2s_dhfile: Path
c2s_protocol_options: [Option, ...]
Example:
c2s_protocol_options: - no_sslv3 - cipher_server_preference - no_compression
c2s_tls_compression: true | false
ca_file: Path
For server connections, this ca_file option is overridden by the s2s_cafile option.
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
captcha_cmd: Path
captcha_host: String
captcha_limit: pos_integer() | infinity
captcha_url: URL
certfiles: [Path, ...]
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
cluster_nodes: [Node, ...]
default_db: mnesia | sql
default_ram_db: mnesia | redis | sql
define_macro: {MacroName: MacroValue}
Example:
define_macro: DEBUG: debug LOG_LEVEL: DEBUG USERBOB: user: bob@localhost loglevel: LOG_LEVEL acl: admin: USERBOB
disable_sasl_mechanisms: [Mechanism, ...]
domain_balancing: {Domain: Options}
component_number: 2..1000
type: random | source | destination | bare_source | bare_destination
Example:
domain_balancing: component.domain.tld: type: destination component_number: 5 transport.example.org: type: bare_source
ext_api_headers: Headers
ext_api_http_pool_size: pos_integer()
ext_api_path_oauth: Path
ext_api_url: URL
extauth_pool_name: Name
extauth_pool_size: Size
extauth_program: Path
fqdn: Domain
hide_sensitive_log_data: true | false
host_config: {Host: Options}
Example:
hosts: - domain.tld - example.org auth_method: - sql host_config: domain.tld: auth_method: - ldap
hosts: [Domain1, Domain2, ...]
include_config_file: [Filename, ...] | {Filename: Options}
allow_only: [OptionName, ...]
disallow: [OptionName, ...]
jwt_auth_only_rule: AccessName
jwt_jid_field: FieldName
jwt_key: FilePath
language: Language
ldap_backups: [Host, ...]
ldap_base: Base
ldap_deref_aliases: never | always | finding | searching
ldap_dn_filter: {Filter: FilterAttrs}
Example:
ldap_dn_filter: "(&(name=%s)(owner=%D)(user=%u@%d))": [sn]
ldap_encrypt: tls | none
ldap_filter: Filter
ldap_password: Password
ldap_port: 1..65535
ldap_rootdn: RootDN
ldap_servers: [Host, ...]
ldap_tls_cacertfile: Path
ldap_tls_certfile: Path
ldap_tls_depth: Number
ldap_tls_verify: false | soft | hard
ldap_uids: [Attr] | {Attr: AttrFormat}
listen: [Options, ...]
log_rotate_count: Number
log_rotate_size: pos_integer() | infinity
loglevel: none | emergency | alert | critical | error | warning | notice | info | debug
max_fsm_queue: Size
modules: {Module: Options}
negotiation_timeout: timeout()
net_ticktime: timeout()
new_sql_schema: true | false
oauth_access: AccessName
oauth_cache_life_time: timeout()
oauth_cache_missed: true | false
oauth_cache_rest_failure_life_time: timeout()
oauth_cache_size: pos_integer() | infinity
oauth_client_id_check: allow | db | deny
oauth_db_type: mnesia | sql
oauth_expire: timeout()
oauth_use_cache: true | false
oom_killer: true | false
oom_queue: Size
oom_watermark: Percent
outgoing_s2s_families: [ipv4 | ipv6, ...]
outgoing_s2s_ipv4_address: Address
outgoing_s2s_ipv6_address: Address
outgoing_s2s_port: 1..65535
outgoing_s2s_timeout: timeout()
pam_service: Name
pam_userinfotype: username | jid
pgsql_users_number_estimate: true | false
queue_dir: Directory
queue_type: ram | file
redis_connect_timeout: timeout()
redis_db: Number
redis_password: Password
redis_pool_size: Number
redis_port: 1..65535
redis_queue_type: ram | file
redis_server: Hostname
registration_timeout: timeout()
resource_conflict: setresource | closeold | closenew
router_cache_life_time: timeout()
router_cache_missed: true | false
router_cache_size: pos_integer() | infinity
router_db_type: mnesia | redis | sql
router_use_cache: true | false
rpc_timeout: timeout()
s2s_access: Access
s2s_cafile: Path
You can use host_config to specify this option per-vhost.
s2s_ciphers: [Cipher, ...]
Example:
s2s_ciphers: - HIGH - "!aNULL" - "!eNULL" - "!3DES" - "@STRENGTH"
s2s_dhfile: Path
s2s_dns_retries: Number
s2s_dns_timeout: timeout()
s2s_max_retry_delay: timeout()
s2s_protocol_options: [Option, ...]
Example:
s2s_protocol_options: - no_sslv3 - cipher_server_preference - no_compression
s2s_queue_type: ram | file
s2s_timeout: timeout()
s2s_tls_compression: true | false
s2s_use_starttls: true | false | optional | required
s2s_zlib: true | false
shaper: {ShaperName: Rate}
Example:
shaper: normal: 1000 fast: 50000
shaper_rules: {ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}
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()
sm_cache_missed: true | false
sm_cache_size: pos_integer() | infinity
sm_db_type: mnesia | redis | sql
sm_use_cache: true | false
sql_connect_timeout: timeout()
sql_database: Database
sql_keepalive_interval: timeout()
sql_odbc_driver: Path
sql_password: Password
sql_pool_size: Size
sql_port: 1..65535
sql_prepared_statements: true | false
sql_query_timeout: timeout()
sql_queue_type: ram | file
sql_server: Host
sql_ssl: true | false
sql_ssl_cafile: Path
sql_ssl_certfile: Path
sql_ssl_verify: true | false
sql_start_interval: timeout()
sql_type: mssql | mysql | odbc | pgsql | sqlite
sql_username: Username
trusted_proxies: all | [Network1, Network2, ...]
use_cache: true | false
validate_stream: true | false
version: string()
websocket_origin: ignore | URL
websocket_ping_interval: timeout()
websocket_timeout: timeout()
MODULES¶
This section describes options of all modules in ejabberd 21.01mod_adhoc¶
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
mod_admin_extra¶
This module provides additional administrative commands.Details for some commands:
Available options:
module_resource: Resource
Examples:
With this configuration, vCards can only be modified with mod_admin_extra commands:
acl: adminextraresource: - resource: "modadminextraf8x,31ad" access_rules: vcard_set: - allow: adminextraresource modules: mod_admin_extra: module_resource: "modadminextraf8x,31ad" mod_vcard: access_set: vcard_set
Content of roster file for pushroster command:
[{<<"bob">>, <<"example.org">>, <<"workers">>, <<"Bob">>}, {<<"mart">>, <<"example.org">>, <<"workers">>, <<"Mart">>}, {<<"Rich">>, <<"example.org">>, <<"bosses">>, <<"Rich">>}].
With this call, the sessions of the local account which JID is boby@example.org will be kicked, and its password will be set to something like BANNED_ACCOUNT—20080425T21:45:07—2176635—Spammed_rooms
ejabberdctl vhost example.org ban-account boby "Spammed rooms"
Call to srg-create using double-quotes and single-quotes:
ejabberdctl srg-create g1 example.org "'Group number 1'" this_is_g1 g1
mod_admin_update_sql¶
This module can be used to update existing SQL database from the default to the new schema. Check the section Default and New Schemas for details. When the module is loaded use update_sql ejabberdctl command.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.Note that this module can be resource intensive on large deployments as it may broadcast a lot of messages. This module should be disabled for instances of ejabberd with hundreds of thousands users.
The Ad-hoc Commands are listed in the Server Discovery. For this feature to work, mod_adhoc must be enabled.
The specific JIDs where messages can be sent are listed below. The first JID in each entry will apply only to the specified virtual host example.org, while the JID between brackets will apply to all virtual hosts in ejabberd:
Available options:
access: AccessName
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
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}
Example:
convert: webp: jpg default: png
rate_limit: Number
mod_block_strangers¶
This module allows one to block/log messages coming from an unknown entity. If a writing entity is not in your roster, you can let this module drop and/or log the message. By default you’ll just not receive message from that entity. Enable this module if you want to drop SPAM messages.Available options:
access: AccessName
allow_local_users: true | false
allow_transports: true | false
captcha: true | false
drop: true | false
log: true | false
mod_blocking¶
The module implements XEP-0191: Blocking Command.This module depends on mod_privacy where all the configuration is performed.
The module has no options.
mod_bosh¶
This module implements XMPP over BOSH as defined in XEP-0124 and XEP-0206. BOSH stands for Bidirectional-streams Over Synchronous HTTP. It makes it possible to simulate long lived connections required by XMPP over the HTTP protocol. In practice, this module makes it possible to use XMPP in a browser without Websocket support and more generally to have a way to use XMPP while having to get through an HTTP proxy.Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
json: true | false
max_concat: pos_integer() | infinity
max_inactivity: timeout()
max_pause: pos_integer()
prebind: true | false
queue_type: ram | file
ram_db_type: mnesia | sql | redis
use_cache: true | false
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()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
mod_carboncopy¶
The module implements XEP-0280: Message Carbons. The module broadcasts messages on all connected user resources (devices).The module has no options.
mod_client_state¶
This module allows for queueing certain types of stanzas when a client indicates that the user is not actively using the client right now (see XEP-0352: Client State Indication). This can save bandwidth and resources.A stanza is dropped from the queue if it’s effectively obsoleted by a new one (e.g., a new presence stanza would replace an old one from the same client). The queue is flushed if a stanza arrives that won’t be queued, or if the queue size reaches a certain limit (currently 100 stanzas), or if the client becomes active again.
Available options:
queue_chat_states: true | false
queue_pep: true | false
queue_presence: true | false
mod_configure¶
The module provides server configuration functionality via XEP-0050: Ad-Hoc Commands. This module requires mod_adhoc to be loaded.The module has no options.
mod_delegation¶
This module is an implementation of XEP-0355: Namespace Delegation. Only admin mode has been implemented by now. Namespace delegation allows external services to handle IQ using specific namespace. This may be applied for external PEP service.Warning
Security issue: Namespace delegation gives components access to sensitive data, so permission should be granted carefully, only if you trust the component.
Note
This module is complementary to mod_privilege but can also be used separately.
Available options:
namespaces: {Namespace: Options}
access: AccessName
filtering: Attributes
Examples:
Make sure you do not delegate the same namespace to several services at the same time. As in the example provided later, to have the sat-pubsub.example.org component perform correctly disable the mod_pubsub module.
access_rules: external_pubsub: allow: external_component external_mam: allow: external_component acl: external_component: server: sat-pubsub.example.org modules: ... mod_delegation: namespaces: urn:xmpp:mam:1: access: external_mam http://jabber.org/protocol/pubsub: access: external_pubsub
mod_disco¶
This module adds support for XEP-0030: Service Discovery. With this module enabled, services on your server can be discovered by XMPP clients.Available options:
extra_domains: [Domain, ...]
name: Name
server_info: [Info, ...]
modules: all | [Module, ...]
name: Name
urls: [URI, ...]
Example:
server_info: - modules: all name: abuse-addresses urls: [mailto:abuse@shakespeare.lit] - modules: [mod_muc] name: "Web chatroom logs" urls: [http://www.example.org/muc-logs] - modules: [mod_disco] name: feedback-addresses urls: - http://shakespeare.lit/feedback.php - mailto:feedback@shakespeare.lit - xmpp:feedback@shakespeare.lit - modules: - mod_disco - mod_vcard name: admin-addresses urls: - mailto:xmpp@shakespeare.lit - xmpp:admins@shakespeare.lit
mod_fail2ban¶
The module bans IPs that show the malicious signs. Currently only C2S authentication failures are detected.Unlike the standalone program, mod_fail2ban clears the record of authentication failures after some time since the first failure or on a successful authentication. It also does not simply block network traffic, but provides the client with a descriptive error message.
Warning
You should not use this module behind a proxy or load balancer. ejabberd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer. You can lock all your user base out of ejabberd when using this module behind a proxy.
Available options:
access: AccessName
c2s_auth_ban_lifetime: timeout()
c2s_max_auth_failures: Number
mod_http_api¶
This module provides a ReST API to call ejabberd commands using JSON data.To use this module, in addition to adding it to the modules section, you must also add it to request_handlers of some listener.
To use a specific API version N, when defining the URL path in the request_handlers, add a vN. For example: /api/v2: mod_http_api
To run a command, send a POST request to the corresponding URL: http://localhost:5280/api/<command_name>
The module has no options.
mod_http_fileserver¶
This simple module serves files from the local disk over HTTP.Available options:
accesslog: Path
content_types: {Extension: Type}
Example:
content_types: .css: text/css .gif: image/gif .html: text/html .jar: application/java-archive .jpeg: image/jpeg .jpg: image/jpeg .js: text/javascript .png: image/png .svg: image/svg+xml .txt: text/plain .xml: application/xml .xpi: application/x-xpinstall .xul: application/vnd.mozilla.xul+xml
custom_headers: {Name: Value}
default_content_type: Type
directory_indices: [Index, ...]
docroot: Path
must_authenticate_with: [{Username, Hostname}, ...]
Examples:
This example configuration will serve the files from the local directory /var/www in the address http://example.org:5280/pub/archive/. In this example a new content type ogg is defined, png is redefined, and jpg definition is deleted:
listen: ... - port: 5280 module: ejabberd_http request_handlers: ... /pub/archive: mod_http_fileserver ... ... modules: ... mod_http_fileserver: docroot: /var/www accesslog: /var/log/ejabberd/access.log directory_indices: - index.html - main.htm custom_headers: X-Powered-By: Erlang/OTP X-Fry: "It's a widely-believed fact!" content_types: .ogg: audio/ogg .png: image/png default_content_type: text/html ...
mod_http_upload¶
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 configured as a request_handler for ejabberd_http listener.
Available options:
access: AccessName
custom_headers: {Name: Value}
dir_mode: Permission
docroot: Path
external_secret: Text
file_mode: Permission
get_url: URL
host
hosts: [Host, ...]
jid_in_url: node | sha1
max_size: Size
name: Name
put_url: URL
rm_on_unregister: true | false
secret_length: Length
service_url
thumbnail: true | false
vcard: vCard
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'> <FN>Conferences</FN> <ADR> <WORK/> <STREET>Elm Street</STREET> </ADR> </vCard>
will be translated to:
vcard: fn: Conferences adr: - work: true street: Elm Street
Example:
listen: ... - port: 5443 module: ejabberd_http tls: true request_handlers: ... /upload: mod_http_upload ... ... modules: ... mod_http_upload: docroot: /ejabberd/upload put_url: "https://@HOST@:5443/upload" ...
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
access_soft_quota: AccessName
max_days: Days
Examples:
Please note that it’s not necessary to specify the access_hard_quota and access_soft_quota options in order to use the quota feature. You can stick to the default names and just specify access rules such as those in this example:
shaper_rules: ... soft_upload_quota: 1000: all # MiB hard_upload_quota: 1100: all # MiB ... modules: ... mod_http_upload: {} mod_http_upload_quota: max_days: 100 ...
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
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()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
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. Compatible XMPP clients can use it to store their chat history on the server.Available options:
access_preferences: AccessName
assume_mam_usage: true | false
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
clear_archive_on_room_destroy: true | false
compress_xml: true | false
db_type: mnesia | sql
default: always | never | roster
request_activates_archiving: true | false
use_cache: true | false
user_mucsub_from_muc_archive: true | false
mod_metrics¶
This module sends events to external backend (by now only grapherl is supported). Supported events are:When enabled, every call to these hooks triggers a counter event to be sent to the external backend.
Available options:
ip: IPv4Address
port: Port
mod_mix¶
This module is an experimental implementation of XEP-0369: Mediated Information eXchange (MIX). MIX support was added in ejabberd 16.03 as an experimental feature, updated in 19.02, and is not yet ready to use in production. It’s asserted that the MIX protocol is going to replace the MUC protocol in the future (see mod_muc).To learn more about how to use that feature, you can refer to our tutorial: Getting started with XEP-0369: Mediated Information eXchange (MIX) v0.1.
The module depends on mod_mam.
Available options:
access_create: AccessName
db_type: mnesia | sql
host
hosts: [Host, ...]
name: Name
mod_mix_pam¶
This module implements XEP-0405: Mediated Information eXchange (MIX): Participant Server Requirements. The module is needed if MIX compatible clients on your server are going to join MIX channels (either on your server or on any remote servers).Note
mod_mix is not required for this module to work, however, without mod_mix_pam the MIX functionality of your local XMPP clients will be impaired.
Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
mod_mqtt¶
This module adds support for the MQTT protocol version 3.1.1 and 5.0. Remember to configure mod_mqtt in modules and listen sections.Available options:
access_publish: {TopicFilter: AccessName}
access_subscribe: {TopicFilter: AccessName}
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
match_retained_limit: pos_integer() | infinity
max_queue: Size
max_topic_aliases: 0..65535
max_topic_depth: Depth
queue_type: ram | file
ram_db_type: mnesia
session_expiry: timeout()
use_cache: true | false
mod_muc¶
This module provides support for XEP-0045: Multi-User Chat. Users can discover existing rooms, join or create them. Occupants of a room can chat in public or have private chats.The MUC service allows any Jabber ID to register a nickname, so nobody else can use that nickname in any room in the MUC service. To register a nickname, open the Service Discovery in your XMPP client and register in the MUC service.
This module supports clustering and load balancing. One module can be started per cluster node. Rooms are distributed at creation time on all available MUC module instances. The multi-user chat module is clustered but the rooms themselves are not clustered nor fault-tolerant: if the node managing a set of rooms goes down, the rooms disappear and they will be recreated on an available node on first connection attempt.
Available options:
access: AccessName
access_admin: AccessName
access_create: AccessName
access_mam: AccessName
access_persistent: AccessName
access_register: AccessName
db_type: mnesia | sql
default_room_options: Options
allow_change_subj: true | false
allow_private_messages: true | false
allow_private_messages_from_visitors: anyone | moderators | nobody
allow_query_users: true | false
allow_subscription: true | false
allow_user_invites: true | false
allow_visitor_nickchange: true | false
allow_visitor_status: true | false
anonymous: true | false
captcha_protected: true | false
lang: Language
logging: true | false
mam: true | false
max_users: Number
members_by_default: true | false
members_only: true | false
moderated: true | false
password: Password
password_protected: true | false
persistent: true | false
presence_broadcast: [moderator | participant | visitor, ...]
Example:
presence_broadcast: - moderator - participant - visitor
public: true | false
public_list: true | false
title: Room Title
hibernation_timeout: infinity | Seconds
history_size: Size
host
hosts: [Host, ...]
max_captcha_whitelist: Number
max_password: Number
max_room_desc: Number
max_room_id: Number
max_room_name: Number
max_rooms_discoitems: Number
max_user_conferences: Number
max_users: Number
max_users_admin_threshold: Number
max_users_presence: Number
min_message_interval: Number
min_presence_interval: Number
name: string()
preload_rooms: true | false
queue_type: ram | file
ram_db_type: mnesia
regexp_room_id: string()
room_shaper: none | ShaperName
user_message_shaper: none | ShaperName
user_presence_shaper: none | ShaperName
vcard: vCard
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'> <FN>Conferences</FN> <ADR> <WORK/> <STREET>Elm Street</STREET> </ADR> </vCard>
will be translated to:
vcard: fn: Conferences adr: - work: true street: Elm Street
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.
The module has no options.
mod_muc_log¶
This module enables optional logging of Multi-User Chat (MUC) public conversations to HTML. Once you enable this module, users can join a room using a MUC capable XMPP client, and if they have enough privileges, they can request the configuration form in which they can set the option to enable room logging.Features:
The module depends on mod_muc.
Available options:
access_log: AccessName
cssfile: Path | URL
dirname: room_jid | room_name
dirtype: subdirs | plain
file_format: html | plaintext
file_permissions: {mode: Mode, group: Group}
Example:
file_permissions: mode: 644 group: 33
outdir: Path
spam_prevention: true | false
timezone: local | universal
top_link: {URL: Text}
Example:
top_link: /: Home
url: URL
mod_multicast¶
This module implements a service for XEP-0033: Extended Stanza Addressing.Available options:
access: Access
host
hosts: [Host, ...]
limits: Sender: Stanza: Number
Example:
# Default values: local: message: 100 presence: 100 remote: message: 20 presence: 20
name
vcard
Example:
# Only admins can send packets to multicast service access_rules: multicast: - allow: admin # If you want to allow all your users: access_rules: multicast: - allow # This allows both admins and remote users to send packets, # but does not allow local users acl: allservers: server_glob: "*" access_rules: multicast: - allow: admin - deny: local - allow: allservers modules: mod_multicast: host: multicast.example.org access: multicast limits: local: message: 40 presence: infinite remote: message: 150
mod_offline¶
This module implements XEP-0160: Best Practices for Handling Offline Messages and XEP-0013: Flexible Offline Message Retrieval. This means that all messages sent to an offline user will be stored on the server until that user comes online again. Thus it is very similar to how email works. A user is considered offline if no session presence priority > 0 are currently open.Note
ejabberdctl has a command to delete expired messages (see chapter Managing an ejabberd server in online documentation.
Available options:
access_max_user_messages: AccessName
bounce_groupchat: true | false
cache_life_time: timeout()
cache_size: pos_integer() | infinity
db_type: mnesia | sql
store_empty_body: true | false | unless_chat_state
store_groupchat: true | false
use_cache: true | false
use_mam_for_storage: true | false
Examples:
This example allows power users to have as much as 5000 offline messages, administrators up to 2000, and all the other users up to 100:
acl: admin: user: - admin1@localhost - admin2@example.org poweruser: user: - bob@example.org - jane@example.org shaper_rules: max_user_offline_messages: - 5000: poweruser - 2000: admin - 100 modules: ... mod_offline: access_max_user_messages: max_user_offline_messages ...
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()
ping_interval: timeout()
send_pings: true | false
timeout_action: none | kill
Example:
modules: ... mod_ping: send_pings: true ping_interval: 4 min timeout_action: kill ...
mod_pres_counter¶
This module detects flood/spam in presence subscriptions traffic. If a user sends or receives more of those stanzas in a given time interval, the exceeding stanzas are silently dropped, and a warning is logged.Available options:
count: Number
interval: timeout()
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 module. However, you still need mod_privacy loaded in order for mod_blocking to work.
Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
mod_private¶
This module adds support for XEP-0049: Private XML Storage.Using this method, XMPP entities can store private data on the server, retrieve it whenever necessary and share it between multiple connected clients of the same user. The data stored might be anything, as long as it is a valid XML. One typical usage is storing a bookmark of all user’s conferences (XEP-0048: Bookmarks).
Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
mod_privilege¶
This module is an implementation of XEP-0356: Privileged Entity. This extension allows components to have privileged access to other entity data (send messages on behalf of the server or on behalf of a user, get/set user roster, access presence information, etc.). This may be used to write powerful external components, for example implementing an external PEP or MAM service.By default a component does not have any privileged access. It is worth noting that the permissions grant access to the component to a specific data type for all users of the virtual host on which mod_privilege is loaded.
Make sure you have a listener configured to connect your component. Check the section about listening ports for more information.
Warning
Security issue: Privileged access gives components access to sensitive data, so permission should be granted carefully, only if you trust a component.
Note
This module is complementary to mod_delegation, but can also be used separately.
Available options:
message: Options
outgoing: AccessName
presence: Options
managed_entity: AccessName
roster: AccessName
roster: Options
both: AccessName
get: AccessName
set: AccessName
Example:
modules: ... mod_privilege: roster: get: all presence: managed_entity: all message: outgoing: all ...
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
auth_type: anonymous | plain
host
hostname: Host
hosts: [Host, ...]
ip: IPAddress
max_connections: pos_integer() | infinity
name: Name
port: 1..65535
ram_db_type: mnesia | redis | sql
recbuf: Size
shaper: Shaper
sndbuf: Size
vcard: vCard
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'> <FN>Conferences</FN> <ADR> <WORK/> <STREET>Elm Street</STREET> </ADR> </vCard>
will be translated to:
vcard: fn: Conferences adr: - work: true street: Elm Street
Example:
acl: admin: user: admin@example.org proxy_users: server: example.org access_rules: proxy65_access: allow: proxy_users shaper_rules: proxy65_shaper: none: admin proxyrate: proxy_users shaper: proxyrate: 10240 modules: ... mod_proxy65: host: proxy1.example.org name: "File Transfer Proxy" ip: 200.150.100.1 port: 7778 max_connections: 5 access: proxy65_access shaper: proxy65_shaper recbuf: 10240 sndbuf: 10240 ...
mod_pubsub¶
This module offers a service for XEP-0060: Publish-Subscribe. The functionality in mod_pubsub can be extended using plugins. The plugin that implements PEP (XEP-0163: Personal Eventing via Pubsub) is enabled in the default ejabberd configuration file, and it requires mod_caps.Available options:
access_createnode: AccessName
db_type: mnesia | sql
default_node_config: List of Key:Value
force_node_config: List of Node and the list of its Key:Value
Example:
force_node_config: ## Avoid buggy clients to make their bookmarks public storage:bookmarks: access_model: whitelist
host
hosts: [Host, ...]
ignore_pep_from_offline: false | true
last_item_cache: false | true
max_items_node: MaxItems
max_nodes_discoitems: pos_integer() | infinity
max_subscriptions_node: MaxSubs
name: Name
nodetree: Nodetree
pep_mapping: List of Key:Value
Example:
modules: ... mod_pubsub: pep_mapping: http://jabber.org/protocol/tune: tune ...
plugins: [Plugin, ...]
vcard: vCard
The following XML representation of vCard:
<vCard xmlns='vcard-temp'> <FN>PubSub Service</FN> <ADR> <WORK/> <STREET>Elm Street</STREET> </ADR> </vCard>
will be translated to:
vcard: fn: PubSub Service adr: - work: true street: Elm Street
Examples:
Example of configuration that uses flat nodes as default, and allows use of flat, hometree and pep nodes:
modules: ... mod_pubsub: access_createnode: pubsub_createnode max_subscriptions_node: 100 default_node_config: notification_type: normal notify_retract: false max_items: 4 plugins: - flat - pep ...
Using relational database requires using mod_pubsub with db_type sql. Only flat, hometree and pep plugins supports SQL. The following example shows previous configuration with SQL usage:
modules: ... mod_pubsub: db_type: sql access_createnode: pubsub_createnode ignore_pep_from_offline: true last_item_cache: false plugins: - flat - pep ...
mod_push¶
This module implements the XMPP server’s part of the push notification solution specified in XEP-0357: Push Notifications. It does not generate, for example, APNS or FCM notifications directly. Instead, it’s designed to work with so-called "app servers" operated by third-party vendors of mobile apps. Those app servers will usually trigger notification delivery to the user’s mobile device using platform-dependant backend services such as FCM or APNS.Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
include_body: true | false | Text
include_sender: true | false
use_cache: true | false
mod_push_keepalive¶
This module tries to keep the stream management session (see mod_stream_mgmt) of a disconnected mobile client alive if the client enabled push notifications for that session. However, the normal session resumption timeout is restored once a push notification is issued, so the session will be closed if the client doesn’t respond to push notifications.The module depends on mod_push.
Available options:
resume_timeout: timeout()
wake_on_start: true | false
wake_on_timeout: true | false
mod_register¶
This module adds support for XEP-0077: In-Band Registration. This protocol enables end users to use an XMPP client to:This module reads also another option defined globally for the server: registration_timeout. Please check that option documentation in the section with top-level options.
Available options:
access: AccessName
access_from: AccessName
access_remove: AccessName
captcha_protected: true | false
ip_access: AccessName
password_strength: Entropy
redirect_url: URL
registration_watchers: [JID, ...]
welcome_message: {subject: Subject, body: Body}
mod_register_web¶
This module provides a web page where users can:This module supports CAPTCHA image to register a new account. To enable this feature, configure the options captcha_cmd and captcha_url, which are documented in the section with top-level options.
As an example usage, the users of the host example.org can visit the page: https://example.org:5281/register/ It is important to include the last / character in the URL, otherwise the subpages URL will be incorrect.
The module depends on mod_register where all the configuration is performed.
The module has no options.
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
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
store_current_id: true | false
use_cache: true | false
versioning: true | false
Example:
modules: ... mod_roster: versioning: true store_current_id: false ...
mod_s2s_dialback¶
The module adds support for XEP-0220: Server Dialback to provide server identity verification based on DNS.Warning
DNS-based verification is vulnerable to DNS cache poisoning, so modern servers rely on verification based on PKIX certificates. Thus this module is only recommended for backward compatibility with servers running outdated software or non-TLS servers, or those with invalid certificates (as long as you accept the risks, e.g. you assume that the remote server has an invalid certificate due to poor administration and not because it’s compromised).
Available options:
access: AccessName
Example:
modules: ... mod_s2s_dialback: access: allow: server: legacy.domain.tld server: invalid-cert.example.org deny: all ...
mod_service_log¶
This module forwards copies of all stanzas to remote XMPP servers or components. Every stanza is encapsulated into <forwarded/> element as described in XEP-0297: Stanza Forwarding.Available options:
loggers: [Domain, ...]
Example:
modules: ... mod_service_log: loggers: - xmpp-server.tld - component.domain.tld ...
mod_shared_roster¶
This module enables you to create shared roster groups: groups of accounts that can see members from (other) groups in their rosters.The big advantages of this feature are that end users do not need to manually add all users to their rosters, and that they cannot permanently delete users from the shared roster groups. A shared roster group can have members from any XMPP server, but the presence will only be available from and to members of the same virtual host where the group is created. It still allows the users to have / add their own contacts, as it does not replace the standard roster. Instead, the shared roster contacts are merged to the relevant users at retrieval time. The standard user rosters thus stay unmodified.
Shared roster groups can be edited via the Web Admin, and some API commands called srg_*. Each group has a unique name and those parameters:
This module depends on mod_roster. If not enabled, roster queries will return 503 errors.
Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql
use_cache: true | false
Examples:
Take the case of a computer club that wants all its members seeing each other in their rosters. To achieve this, they need to create a shared roster group similar to this one:
Name: club_members Label: Club Members Description: Members from the computer club Members: member1@example.org, member2@example.org, member3@example.org Displayed Groups: club_members
In another case we have a company which has three divisions: Management, Marketing and Sales. All group members should see all other members in their rosters. Additionally, all managers should have all marketing and sales people in their roster. Simultaneously, all marketeers and the whole sales team should see all managers. This scenario can be achieved by creating shared roster groups as shown in the following lists:
First list: Name: management Label: Management Description: Management Members: manager1@example.org, manager2@example.org Displayed: management, marketing, sales Second list: Name: marketing Label: Marketing Description: Marketing Members: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org Displayed: management, marketing Third list: Name: sales Label: Sales Description: Sales Members: salesman1@example.org, salesman2@example.org, salesman3@example.org Displayed: management, sales
mod_shared_roster_ldap¶
This module lets the server administrator automatically populate users' rosters (contact lists) with entries based on users and groups defined in an LDAP-based directory.Note
mod_shared_roster_ldap depends on mod_roster being enabled. Roster queries will return 503 errors if mod_roster is not enabled.
The module accepts many configuration options. Some of them, if unspecified, default to the values specified for the top level of configuration. This lets you avoid specifying, for example, the bind password in multiple places.
Check also the Configuration examples section to get details about retrieving the roster, and configuration examples including Flat DIT and Deep DIT.
Available options:
cache_life_time
cache_missed
cache_size
ldap_auth_check: true | false
ldap_backups
ldap_base
ldap_deref_aliases
ldap_encrypt
ldap_filter
ldap_gfilter
ldap_groupattr
ldap_groupdesc
ldap_memberattr
ldap_memberattr_format
ldap_memberattr_format_re
ldap_password
ldap_port
ldap_rfilter
ldap_rootdn
ldap_servers
ldap_tls_cacertfile
ldap_tls_certfile
ldap_tls_depth
ldap_tls_verify
ldap_ufilter
ldap_uids
ldap_userdesc
ldap_userjidattr
ldap_useruid
use_cache
mod_sic¶
This module adds support for XEP-0279: Server IP Check. This protocol enables a client to discover its external IP address.Warning
The protocol extension is deferred and seems like there are no clients supporting it, so using this module is not recommended and, furthermore, the module might be removed in the future.
The module has no options.
mod_sip¶
This module adds SIP proxy/registrar support for the corresponding virtual host.Note
It is not enough to just load this module. You should also configure listeners and DNS records properly. For details see the section about the ejabberd_sip listen module in the ejabberd Documentation.
Available options:
always_record_route: true | false
flow_timeout_tcp: timeout()
flow_timeout_udp: timeout()
record_route: URI
routes: [URI, ...]
via: [URI, ...]
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:Note
The protocol extension is deferred and seems like even a few clients that were supporting it are now abandoned. So using this module makes very little sense.
The module has no options.
mod_stream_mgmt¶
This module adds support for XEP-0198: Stream Management. This protocol allows active management of an XML stream between two XMPP entities, including features for stanza acknowledgements and stream resumption.Available options:
ack_timeout: timeout()
cache_life_time: timeout()
cache_size: pos_integer() | infinity
max_ack_queue: Size
max_resume_timeout: timeout()
queue_type: ram | file
resend_on_timeout: true | false | if_offline
resume_timeout: timeout()
mod_stun_disco¶
This module allows XMPP clients to discover STUN/TURN services and to obtain temporary credentials for using them as per XEP-0215: External Service Discovery.Available options:
access: AccessName
credentials_lifetime: timeout()
offer_local_services: true | false
secret: Text
services: [Service, ...]
host: Host
port: 1..65535
restricted: true | false
transport: tcp | udp
type: stun | turn | stuns | turns
Example:
services: - host: 203.0.113.3 port: 3478 type: stun transport: udp restricted: false - host: 203.0.113.3 port: 3478 type: turn transport: udp restricted: true - host: 2001:db8::3 port: 3478 type: stun transport: udp restricted: false - host: 2001:db8::3 port: 3478 type: turn transport: udp restricted: true - host: server.example.com port: 5349 type: turns transport: tcp restricted: true
mod_time¶
This module adds support for XEP-0202: Entity Time. In other words, the module reports server’s system time.The module has no options.
mod_vcard¶
This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in XEP-0054: vcard-temp. The module also implements an uncomplicated Jabber User Directory based on the vCards of these users. Moreover, it enables the server to send its vCard when queried.Available options:
allow_return_all: true | false
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
db_type: mnesia | sql | ldap
host
hosts: [Host, ...]
matches: pos_integer() | infinity
name: Name
search: true | false
use_cache: true | false
vcard: vCard
For example, the following XML representation of vCard:
<vCard xmlns='vcard-temp'> <FN>Conferences</FN> <ADR> <WORK/> <STREET>Elm Street</STREET> </ADR> </vCard>
will be translated to:
vcard: fn: Conferences adr: - work: true street: Elm Street
Available options for ldap backend:
ldap_backups
ldap_base
ldap_deref_aliases
ldap_encrypt
ldap_filter
ldap_password
ldap_port
ldap_rootdn
ldap_search_fields: {Name: Attribute, ...}
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}, ...}
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
ldap_tls_cacertfile
ldap_tls_certfile
ldap_tls_depth
ldap_tls_verify
ldap_uids
ldap_vcard_map: {Name: {Pattern, LDAPattributes}, ...}
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
mod_vcard_xupdate¶
The user’s client can store an avatar in the user vCard. The vCard-Based Avatars protocol (XEP-0153) provides a method for clients to inform the contacts what is the avatar hash value. However, simple or small clients may not implement that protocol.If this module is enabled, all the outgoing client presence stanzas get automatically the avatar hash on behalf of the client. So, the contacts receive the presence stanzas with the Update Data described in XEP-0153 as if the client would had inserted it itself. If the client had already included such element in the presence stanza, it is replaced with the element generated by ejabberd.
By enabling this module, each vCard modification produces a hash recalculation, and each presence sent by a client produces hash retrieval and a presence stanza rewrite. For this reason, enabling this module will introduce a computational overhead in servers with clients that change frequently their presence. However, the overhead is significantly reduced by the use of caching, so you probably don’t want to set use_cache to false.
The module depends on mod_vcard.
Note
Nowadays XEP-0153 is used mostly as "read-only", i.e. modern clients don’t publish their avatars inside vCards. Thus in the majority of cases the module is only used along with mod_avatar module for providing backward compatibility.
Available options:
cache_life_time: timeout()
cache_missed: true | false
cache_size: pos_integer() | infinity
use_cache: true | false
mod_version¶
This module implements XEP-0092: Software Version. Consequently, it answers ejabberd’s version when queried.Available options:
show_os: true | false
LISTENERS¶
This section describes options of all listeners in ejabberd 21.01TODO
AUTHOR¶
ProcessOne.VERSION¶
This document describes the configuration file of ejabberd 21.01. Configuration options of other ejabberd versions may differ significantly.REPORTING BUGS¶
Report bugs to https://github.com/processone/ejabberd/issuesSEE ALSO¶
Default configuration file: https://github.com/processone/ejabberd/blob/21.01/ejabberd.yml.exampleMain 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-2021 ProcessOne.01/27/2021 |