1EJABBERD.YML(5) EJABBERD.YML(5)
2
3
4
6 ejabberd.yml - main configuration file for ejabberd.
7
9 ejabberd.yml
10
12 The configuration file is written in YAML language.
13
14 Warning
15 YAML is indentation sensitive, so make sure you respect
16 indentation, or otherwise you will get pretty cryptic configuration
17 errors.
18
19 Logically, configuration options are splitted into 3 main categories:
20 Modules, Listeners and everything else called Top Level options. Thus
21 this document is splitted into 3 main chapters describing each category
22 separately. So, the contents of ejabberd.yml will typically look like
23 this:
24
25 hosts:
26 - example.com
27 - domain.tld
28 loglevel: info
29 ...
30 listen:
31 -
32 port: 5222
33 module: ejabberd_c2s
34 ...
35 modules:
36 mod_roster: {}
37 ...
38
39 Any configuration error (such as syntax error, unknown option or
40 invalid option value) is fatal in the sense that ejabberd will refuse
41 to load the whole configuration file and will not start or will abort
42 configuration reload.
43
44 All options can be changed in runtime by running ejabberdctl
45 reload-config command. Configuration reload is atomic: either all
46 options are accepted and applied simultaneously or the new
47 configuration is refused without any impact on currently running
48 configuration.
49
50 Some options can be specified for particular virtual host(s) only using
51 host_config or append_host_config options. Such options are called
52 local. Examples are modules, auth_method and default_db. The options
53 that cannot be defined per virtual host are called global. Examples are
54 loglevel, certfiles and listen. It is a configuration mistake to put
55 global options under host_config or append_host_config section -
56 ejabberd will refuse to load such configuration.
57
58 It is not recommended to write ejabberd.yml from scratch. Instead it is
59 better to start from "default" configuration file available at
60 https://github.com/processone/ejabberd/blob/20.04/ejabberd.yml.example.
61 Once you get ejabberd running you can start changing configuration
62 options to meet your requirements.
63
64 Note that this document is intended to provide comprehensive
65 description of all configuration options that can be consulted to
66 understand the meaning of a particular option, its format and possible
67 values. It will be quite hard to understand how to configure ejabberd
68 by reading this document only - for this purpose the reader is
69 recommended to read online Configuration Guide available at
70 https://docs.ejabberd.im/admin/configuration.
71
73 This section describes top level options of ejabberd 20.04
74
75 access_rules: {AccessName: {allow|deny: ACLRules|ACLName}}
76 The option specifies access rules. Each access rule is assigned a
77 name that can be referenced from other parts of the configuration
78 file (mostly from access options of ejabberd modules). Each rule
79 definition may contain arbitrary number of allow or deny sections,
80 and each section may contain any number of ACL rules (see acl
81 option). There are no access rules defined by default.
82
83 Example:
84
85 access_rules:
86 configure:
87 allow: admin
88 something:
89 deny: someone
90 allow: all
91 s2s_banned:
92 deny: problematic_hosts
93 deny: banned_forever
94 deny:
95 ip: 222.111.222.111/32
96 deny:
97 ip: 111.222.111.222/32
98 allow: all
99 xmlrpc_access:
100 allow:
101 user: peter@example.com
102 allow:
103 user: ivone@example.com
104 allow:
105 user: bot@example.com
106 ip: 10.0.0.0/24
107
108 acl: {ACLName: {ACLType: ACLValue}}
109 The option defines access control lists: named sets of rules which
110 are used to match against different targets (such as a JID or an IP
111 address). Every set of rules has name ACLName: it can be any string
112 except all or none (those are predefined names for the rules that
113 match all or nothing respectively). The name ACLName can be
114 referenced from other parts of the configuration file, for example
115 in access_rules option. The rules of ACLName are represented by
116 mapping {ACLType: ACLValue}. These can be one of the following:
117
118 ip: Network
119 The rule matches any IP address from the Network.
120
121 node_glob: Pattern
122 Same as node_regexp, but matching is performed on a specified
123 Pattern according to the rules used by the Unix shell.
124
125 node_regexp: user_regexp@server_regexp
126 The rule matches any JID with node part matching regular
127 expression user_regexp and server part matching regular
128 expression server_regexp.
129
130 resource: Resource
131 The rule matches any JID with a resource Resource.
132
133 resource_glob: Pattern
134 Same as resource_regexp, but matching is performed on a
135 specified Pattern according to the rules used by the Unix
136 shell.
137
138 resource_regexp: Regexp
139 The rule matches any JID with a resource that matches regular
140 expression Regexp.
141
142 server: Server
143 The rule matches any JID from server Server. The value of
144 Server must be a valid hostname or an IP address.
145
146 server_glob: Pattern
147 Same as server_regexp, but matching is performed on a specified
148 Pattern according to the rules used by the Unix shell.
149
150 server_regexp: Regexp
151 The rule matches any JID from the server that matches regular
152 expression Regexp.
153
154 user: Username
155 If Username is in the form of "user@server", the rule matches a
156 JID against this value. Otherwise, if Username is in the form
157 of "user", the rule matches any JID that has Username in the
158 node part as long as the server part of this JID is any virtual
159 host served by ejabberd.
160
161 user_glob: Pattern
162 Same as user_regexp, but matching is performed on a specified
163 Pattern according to the rules used by the Unix shell.
164
165 user_regexp: Regexp
166 If Regexp is in the form of "regexp@server", the rule matches
167 any JID with node part matching regular expression "regexp" as
168 long as the server part of this JID is equal to "server". If
169 Regexp is in the form of "regexp", the rule matches any JID
170 with node part matching regular expression "regexp" as long as
171 the server part of this JID is any virtual host served by
172 ejabberd.
173
174 acme: Options
175 ACME configuration, to automatically obtain SSL certificates for
176 the domains served by ejabberd, which means that certificate
177 requests and renewals are performed to some CA server (aka "ACME
178 server") in a fully automated mode. The Options are:
179
180 auto: true | false
181 Whether to automatically request certificates for all
182 configured domains (that yet have no a certificate) on server
183 start or configuration reload. The default is true.
184
185 ca_url: URL
186 The ACME directory URL used as an entry point for the ACME
187 server. The default value is
188 https://acme-v02.api.letsencrypt.org/directory - the directory
189 URL of Let’s Encrypt authority.
190
191 cert_type: rsa | ec
192 A type of a certificate key. Available values are ec and rsa
193 for EC and RSA certificates respectively. It’s better to have
194 RSA certificates for the purpose of backward compatibility with
195 legacy clients and servers, thus the default is rsa.
196
197 contact: [Contact, ...]
198 A list of contact addresses (typically emails) where an ACME
199 server will send notifications when problems occur. The value
200 of Contact must be in the form of "scheme:address" (e.g.
201 "mailto:user@domain.tld"). The default is an empty list which
202 means an ACME server will send no notices.
203
204 Example:
205
206 acme:
207 ca_url: https://acme-v02.api.letsencrypt.org/directory
208 contact:
209 - mailto:admin@domain.tld
210 - mailto:bot@domain.tld
211 auto: true
212 cert_type: rsa
213
214 allow_contrib_modules: true | false
215 Whether to allow installation of third-party modules or not. The
216 default value is true.
217
218 allow_multiple_connections: true | false
219 This option is only used when the anonymous mode is enabled.
220 Setting it to true means that the same username can be taken
221 multiple times in anonymous login mode if different resource are
222 used to connect. This option is only useful in very special
223 occasions. The default value is false.
224
225 anonymous_protocol: login_anon | sasl_anon | both
226 login_anon means that the anonymous login method will be used.
227 sasl_anon means that the SASL Anonymous method will be used. both
228 means that SASL Anonymous and login anonymous are both enabled. The
229 default value is sasl_anon.
230
231 api_permissions: [Permission, ...]
232 Define the permissions for API access. Please consult the ejabberd
233 Docs web → For Developers → ejabberd ReST API → API Permissions.
234
235 append_host_config: {Host: Options}
236 To define specific ejabberd modules in a virtual host, you can
237 define the global modules option with the common modules, and later
238 add specific modules to certain virtual hosts. To accomplish that,
239 append_host_config option can be used.
240
241 auth_cache_life_time: timeout()
242 Same as cache_life_time, but applied to authentication cache only.
243 If not set, the value from cache_life_time will be used.
244
245 auth_cache_missed: true | false
246 Same as cache_missed, but applied to authentication cache only. If
247 not set, the value from cache_missed will be used.
248
249 auth_cache_size: pos_integer() | infinity
250 Same as cache_size, but applied to authentication cache only. If
251 not set, the value from cache_size will be used.
252
253 auth_method: [mnesia | sql | anonymous | external | jwt | ldap | pam,
254 ...]
255 A list of authentication methods to use. If several methods are
256 defined, authentication is considered successful as long as
257 authentication of at least one of the methods succeeds. The default
258 value is [mnesia].
259
260 auth_opts: [Option, ...]
261 This is used by the contributed module ejabberd_auth_http that can
262 be installed from the ejabberd-contrib Git repository. Please refer
263 to that module’s README file for details.
264
265 auth_password_format: plain | scram
266 The option defines in what format the users passwords are stored.
267 plain: The password is stored as plain text in the database. This
268 is risky because the passwords can be read if your database gets
269 compromised. This is the default value. This format allows clients
270 to authenticate using: the old Jabber Non-SASL (XEP-0078), SASL
271 PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1. scram: The password
272 is not stored, only some information that allows to verify the hash
273 provided by the client. It is impossible to obtain the original
274 plain password from the stored information; for this reason, when
275 this value is configured it cannot be changed to plain anymore.
276 This format allows clients to authenticate using: SASL PLAIN and
277 SASL SCRAM-SHA-1.
278
279 auth_use_cache: true | false
280 Same as use_cache, but applied to authentication cache only. If not
281 set, the value from use_cache will be used.
282
283 c2s_cafile: Path
284 Full path to a file containing one or more CA certificates in PEM
285 format. All client certificates should be signed by one of these
286 root CA certificates and should contain the corresponding JID(s) in
287 subjectAltName field. There is no default value.
288
289 c2s_ciphers: [Cipher, ...]
290 A list of OpenSSL ciphers to use for c2s connections. The default
291 value is shown in the example below:
292
293 Example:
294
295 c2s_ciphers:
296 - HIGH
297 - "!aNULL"
298 - "!eNULL"
299 - "!3DES"
300 - "@STRENGTH"
301
302 c2s_dhfile: Path
303 Full path to a file containing custom DH parameters to use for c2s
304 connections. Such a file could be created with the command "openssl
305 dhparam -out dh.pem 2048". If this option is not specified,
306 2048-bit MODP Group with 256-bit Prime Order Subgroup will be used
307 as defined in RFC5114 Section 2.3.
308
309 c2s_protocol_options: [Option, ...]
310 List of general SSL options to use for c2s connections. These map
311 to OpenSSL’s set_options(). The default value is shown in the
312 example below:
313
314 Example:
315
316 c2s_protocol_options:
317 - no_sslv3
318 - cipher_server_preference
319 - no_compression
320
321 c2s_tls_compression: true | false
322 Whether to enable or disable TLS compression for c2s connections.
323 The default value is false.
324
325 ca_file: Path
326 Path to a file of CA root certificates. The default is to use
327 system defined file if possible.
328
329 cache_life_time: timeout()
330 The time of a cached item to keep in cache. Once it’s expired, the
331 corresponding item is erased from cache. The default value is one
332 hour. Several modules have a similar option; and some core ejabberd
333 parts support similar options too, see auth_cache_life_time,
334 oauth_cache_life_time, router_cache_life_time, and
335 sm_cache_life_time.
336
337 cache_missed: true | false
338 Whether or not to cache missed lookups. When there is an attempt to
339 lookup for a value in a database and this value is not found and
340 the option is set to true, this attempt will be cached and no
341 attempts will be performed until the cache expires (see
342 cache_life_time). Usually you don’t want to change it. Default is
343 true. Several modules have a similar option; and some core ejabberd
344 parts support similar options too, see auth_cache_missed,
345 oauth_cache_missed, router_cache_missed, and sm_cache_missed.
346
347 cache_size: pos_integer() | infinity
348 A maximum number of items (not memory!) in cache. The rule of
349 thumb, for all tables except rosters, you should set it to the
350 number of maximum online users you expect. For roster multiply this
351 number by 20 or so. If the cache size reaches this threshold, it’s
352 fully cleared, i.e. all items are deleted, and the corresponding
353 warning is logged. You should avoid frequent cache clearance,
354 because this degrades performance. The default value is 1000.
355 Several modules have a similar option; and some core ejabberd parts
356 support similar options too, see auth_cache_size, oauth_cache_size,
357 router_cache_size, and sm_cache_size.
358
359 captcha_cmd: Path
360 Full path to a script that generates CAPTCHA images. There is no
361 default value: when this option is not set, CAPTCHA functionality
362 is completely disabled.
363
364 captcha_host: String
365 Deprecated. Use captcha_url instead.
366
367 captcha_limit: pos_integer() | infinity
368 Maximum number of CAPTCHA generated images per minute for any given
369 JID. The option is intended to protect the server from CAPTCHA DoS.
370 The default value is infinity.
371
372 captcha_url: URL
373 An URL where CAPTCHA requests should be sent. NOTE: you need to
374 configure request_handlers for ejabberd_http listener as well.
375 There is no default value.
376
377 certfiles: [Path, ...]
378 The option accepts a list of file paths (optionally with wildcards)
379 containing either PEM certificates or PEM private keys. At startup
380 or configuration reload, ejabberd reads all certificates from these
381 files, sorts them, removes duplicates, finds matching private keys
382 and then rebuilds full certificate chains for the use in TLS
383 connections. Use this option when TLS is enabled in either of
384 ejabberd listeners: ejabberd_c2s, ejabberd_http and so on. NOTE: if
385 you modify the certificate files or change the value of the option,
386 run ejabberdctl reload-config in order to rebuild and reload the
387 certificate chains.
388
389 If you use Let’s Encrypt certificates for your domain "domain.tld",
390 the configuration will look like this:
391
392 certfiles:
393 - /etc/letsencrypt/live/domain.tld/fullchain.pem
394 - /etc/letsencrypt/live/domain.tld/privkey.pem
395
396 cluster_backend: Backend
397 A database backend to use for storing information about cluster.
398 The only available value so far is mnesia.
399
400 cluster_nodes: [Node, ...]
401 A list of Erlang nodes to connect on ejabberd startup. This option
402 is mostly intended for ejabberd customization and sophisticated
403 setups. The default value is an empty list.
404
405 default_db: mnesia | sql
406 Default persistent storage for ejabberd. Modules and other
407 components (e.g. authentication) may have its own value. The
408 default value is mnesia.
409
410 default_ram_db: mnesia | sql | redis
411 Default volatile (in-memory) storage for ejabberd. Modules and
412 other components (e.g. session management) may have its own value.
413 The default value is mnesia.
414
415 define_macro: {MacroName: MacroValue}
416 Defines a macro. The value can be any valid arbitrary YAML value.
417 For convenience, it’s recommended to define a MacroName in capital
418 letters. Duplicated macros are not allowed. Macros are processed
419 after additional configuration files have been included, so it is
420 possible to use macros that are defined in configuration files
421 included before the usage. It is possible to use a MacroValue in
422 the definition of another macro.
423
424 Example:
425
426 define_macro:
427 DEBUG: debug
428 LOG_LEVEL: DEBUG
429 USERBOB:
430 user: bob@localhost
431
432 loglevel: LOG_LEVEL
433
434 acl:
435 admin: USERBOB
436
437 disable_sasl_mechanisms: [Mechanism, ...]
438 Specify a list of SASL mechanisms (such as DIGEST-MD5 or
439 SCRAM-SHA1) that should not be offered to the client. For
440 convenience, the value of Mechanism is case-insensitive. The
441 default value is an empty list, i.e. no mechanisms are disabled by
442 default.
443
444 domain_balancing: {Domain: Options}
445 An algorithm to load balance the components that are plugged on an
446 ejabberd cluster. It means that you can plug one or several
447 instances of the same component on each ejabberd node and that the
448 traffic will be automatically distributed. The algorithm to deliver
449 messages to the component(s) can be specified by this option. For
450 any component connected as Domain, available Options are:
451
452 component_number: 2..1000
453 The number of components to balance.
454
455 type: random | source | destination | bare_source |
456 bare_destination
457 How to deliver stanzas to connected components: random - an
458 instance is chosen at random; destination - an instance is
459 chosen by the full JID of the packet’s to attribute; source -
460 by the full JID of the packet’s from attribute;
461 bare_destination - by the the bare JID (without resource) of
462 the packet’s to attribute; bare_source - by the bare JID
463 (without resource) of the packet’s from attribute is used. The
464 default value is random.
465
466 Example:
467
468 domain_balancing:
469 component.domain.tld:
470 type: destination
471 component_number: 5
472 transport.example.org:
473 type: bare_source
474
475 ext_api_headers: Headers
476 String of headers (separated with commas ,) that will be provided
477 by ejabberd when sending ReST requests. The default value is an
478 empty string of headers: "".
479
480 ext_api_http_pool_size: pos_integer()
481 Define the size of the HTTP pool, that is, the maximum number of
482 sessions that the ejabberd ReST service will handle simultaneously.
483 The default value is: 100.
484
485 ext_api_path_oauth: Path
486 Define the base URI path when performing OAUTH ReST requests. The
487 default value is: "/oauth".
488
489 ext_api_url: URL
490 Define the base URI when performing ReST requests. The default
491 value is: "http://localhost/api".
492
493 extauth_pool_name: Name
494 Define the pool name appendix, so the full pool name will be
495 extauth_pool_Name. The default value is the hostname.
496
497 extauth_pool_size: Size
498 The option defines the number of instances of the same external
499 program to start for better load balancing. The default is the
500 number of available CPU cores.
501
502 extauth_program: Path
503 Indicate in this option the full path to the external
504 authentication script. The script must be executable by ejabberd.
505
506 fqdn: Domain
507 A fully qualified domain name that will be used in SASL DIGEST-MD5
508 authentication. The default is detected automatically.
509
510 hide_sensitive_log_data: true | false
511 A privacy option to not log sensitive data (mostly IP addresses).
512 The default value is false for backward compatibility.
513
514 host_config: {Host: Options}
515 The option is used to redefine Options for virtual host Host. In
516 the example below LDAP authentication method will be used on
517 virtual host domain.tld and SQL method will be used on virtual host
518 example.org.
519
520 Example:
521
522 hosts:
523 - domain.tld
524 - example.org
525
526 auth_method:
527 - sql
528
529 host_config:
530 domain.tld:
531 auth_method:
532 - ldap
533
534 hosts: [Domain1, Domain2, ...]
535 The option defines a list containing one or more domains that
536 ejabberd will serve. This is a mandatory option.
537
538 include_config_file: [Filename, ...] | {Filename: Options}
539 Read additional configuration from Filename. If the value is
540 provided in {Filename: Options} format, the Options must be one of
541 the following:
542
543 allow_only: [OptionName, ...]
544 Allows only the usage of those options in the included file
545 Filename. The options that do not match this criteria are not
546 accepted. The default value is to include all options.
547
548 disallow: [OptionName, ...]
549 Disallows the usage of those options in the included file
550 Filename. The options that match this criteria are not
551 accepted. The default value is an empty list.
552
553 jwt_auth_only_rule: AccessName
554 This ACL rule defines accounts that can use only this auth method,
555 even if others are also defined in the ejabberd configuration file.
556 In other words: if there are several auth methods enabled for this
557 host (JWT, SQL, ...), users that match this rule can only use JWT.
558 The default value is none.
559
560 jwt_jid_field: FieldName
561 By default, the JID is defined in the "jid" JWT field. This option
562 allows to specify other JWT field name where the JID is defined.
563
564 jwt_key: FilePath
565 Path to the file that contains the JWK Key. The default value is
566 undefined.
567
568 language: Language
569 The option defines the default language of server strings that can
570 be seen by XMPP clients. If an XMPP client does not possess
571 xml:lang attribute, the specified language is used.
572
573 ldap_backups: [Host, ...]
574 A list of IP addresses or DNS names of LDAP backup servers. When no
575 servers listed in ldap_servers option are reachable, ejabberd will
576 try to connect to these backup servers. The default is an empty
577 list, i.e. no backup servers specified. WARNING: ejabberd doesn’t
578 try to reconnect back to the main servers when they become
579 operational again, so the only way to restore these connections is
580 to restart ejabberd. This limitation might be fixed in future
581 releases.
582
583 ldap_base: Base
584 LDAP base directory which stores users accounts. There is no
585 default value: you must set the option in order for LDAP
586 connections to work properly.
587
588 ldap_deref_aliases: never | always | finding | searching
589 Whether to dereference aliases or not. The default value is never.
590
591 ldap_dn_filter: {Filter: FilterAttrs}
592 This filter is applied on the results returned by the main filter.
593 The filter performs an additional LDAP lookup to make the complete
594 result. This is useful when you are unable to define all filter
595 rules in ldap_filter. You can define "%u", "%d", "%s" and "%D"
596 pattern variables in Filter: "%u" is replaced by a user’s part of
597 the JID, "%d" is replaced by the corresponding domain (virtual
598 host), all "%s" variables are consecutively replaced by values from
599 the attributes in FilterAttrs and "%D" is replaced by Distinguished
600 Name from the result set. There is no default value, which means
601 the result is not filtered. WARNING: Since this filter makes
602 additional LDAP lookups, use it only as the last resort: try to
603 define all filter rules in ldap_filter option if possible.
604
605 Example:
606
607 ldap_dn_filter:
608 "(&(name=%s)(owner=%D)(user=%u@%d))": [sn]
609
610 ldap_encrypt: tls | none
611 Whether to encrypt LDAP connection using TLS or not. The default
612 value is none. NOTE: STARTTLS encryption is not supported.
613
614 ldap_filter: Filter
615 An LDAP filter as defined in RFC4515. There is no default value.
616 Example: "(&(objectClass=shadowAccount)(memberOf=Jabber Users))".
617 NOTE: don’t forget to close brackets and don’t use superfluous
618 whitespaces. Also you must not use "uid" attribute in the filter
619 because this attribute will be appended to the filter
620 automatically.
621
622 ldap_password: Password
623 Bind password. The default value is an empty string.
624
625 ldap_port: 1..65535
626 Port to connect to your LDAP server. The default port is 389 if
627 encryption is disabled and 636 if encryption is enabled.
628
629 ldap_rootdn: RootDN
630 Bind Distinguished Name. The default value is an empty string,
631 which means "anonymous connection".
632
633 ldap_servers: [Host, ...]
634 A list of IP addresses or DNS names of your LDAP servers. The
635 default value is [localhost].
636
637 ldap_tls_cacertfile: Path
638 A path to a file containing PEM encoded CA certificates. This
639 option is required when TLS verification is enabled.
640
641 ldap_tls_certfile: Path
642 A path to a file containing PEM encoded certificate along with PEM
643 encoded private key. This certificate will be provided by ejabberd
644 when TLS enabled for LDAP connections. There is no default value,
645 which means no client certificate will be sent.
646
647 ldap_tls_depth: Number
648 Specifies the maximum verification depth when TLS verification is
649 enabled, i.e. how far in a chain of certificates the verification
650 process can proceed before the verification is considered to be
651 failed. Peer certificate = 0, CA certificate = 1, higher level CA
652 certificate = 2, etc. The value 2 thus means that a chain can at
653 most contain peer cert, CA cert, next CA cert, and an additional CA
654 cert. The default value is 1.
655
656 ldap_tls_verify: false | soft | hard
657 This option specifies whether to verify LDAP server certificate or
658 not when TLS is enabled. When hard is set, ejabberd doesn’t proceed
659 if the certificate is invalid. When soft is set, ejabberd proceeds
660 even if the check has failed. The default is false, which means no
661 checks are performed.
662
663 ldap_uids: [Attr] | {Attr: AttrFormat}
664 LDAP attributes which hold a list of attributes to use as
665 alternatives for getting the JID, where Attr is an LDAP attribute
666 which holds the user’s part of the JID and AttrFormat must contain
667 one and only one pattern variable "%u" which will be replaced by
668 the user’s part of the JID. For example, "%u@example.org". If the
669 value is in the form of [Attr] then AttrFormat is assumed to be
670 "%u".
671
672 listen: [Options, ...]
673 The option for listeners configuration. See the Listen Modules
674 section for details.
675
676 log_rotate_count: Number
677 The number of rotated log files to keep. The default value is 1.
678
679 log_rotate_size: Size
680 The size (in bytes) of a log file to trigger rotation. The default
681 value is 10485760 (10 Mb).
682
683 loglevel: none | emergency | alert | critical | error | warning |
684 notice | info | debug
685 Verbosity of log files generated by ejabberd. The default value is
686 info. NOTE: previous versions of ejabberd had log levels defined in
687 numeric format (0..5). The numeric values are still accepted for
688 backward compatibility, but are not recommended.
689
690 max_fsm_queue: Size
691 This option specifies the maximum number of elements in the queue
692 of the FSM (Finite State Machine). Roughly speaking, each message
693 in such queues represents one XML stanza queued to be sent into its
694 relevant outgoing stream. If queue size reaches the limit (because,
695 for example, the receiver of stanzas is too slow), the FSM and the
696 corresponding connection (if any) will be terminated and error
697 message will be logged. The reasonable value for this option
698 depends on your hardware configuration. The allowed values are
699 positive integers. The default value is 10000.
700
701 modules: {Module: Options}
702 The option for modules configuration. See Modules section for
703 details.
704
705 negotiation_timeout: timeout()
706 Time to wait for an XMPP stream negotiation to complete. When
707 timeout occurs, the corresponding XMPP stream is closed. The
708 default value is 30 seconds.
709
710 net_ticktime: timeout()
711 This option can be used to tune tick time parameter of net_kernel.
712 It tells Erlang VM how often nodes should check if intra-node
713 communication was not interrupted. This option must have identical
714 value on all nodes, or it will lead to subtle bugs. Usually leaving
715 default value of this is option is best, tweak it only if you know
716 what you are doing. The default value is 1 minute.
717
718 new_sql_schema: true | false
719 Whether to use new SQL schema. All schemas are located at
720 https://github.com/processone/ejabberd/tree/20.04/sql. There are
721 two schemas available. The default legacy schema allows to store
722 one XMPP domain into one ejabberd database. The new schema allows
723 to handle several XMPP domains in a single ejabberd database. Using
724 this new schema is best when serving several XMPP domains and/or
725 changing domains from time to time. This avoid need to manage
726 several databases and handle complex configuration changes. The
727 default depends on configuration flag --enable-new-sql-schema which
728 is set at compile time.
729
730 oauth_access: AccessName
731 By default creating OAuth tokens is not allowed. To define which
732 users can create OAuth tokens, you can refer to an ejabberd access
733 rule in the oauth_access option. Use all to allow everyone to
734 create tokens.
735
736 oauth_cache_life_time: timeout()
737 Same as cache_life_time, but applied to OAuth cache only. If not
738 set, the value from cache_life_time will be used.
739
740 oauth_cache_missed: true | false
741 Same as cache_missed, but applied to OAuth cache only. If not set,
742 the value from cache_missed will be used.
743
744 oauth_cache_size: pos_integer() | infinity
745 Same as cache_size, but applied to OAuth cache only. If not set,
746 the value from cache_size will be used.
747
748 oauth_client_id_check: allow | db | deny
749 Define whether the client authentication is always allowed, denied,
750 or it will depend if the client ID is present in the database. The
751 default value is allow.
752
753 oauth_db_type: mnesia | sql
754 Database backend to use for OAuth authentication. The default value
755 is picked from default_db option, or if it’s not set, mnesia will
756 be used.
757
758 oauth_expire: timeout()
759 Time during which the OAuth token is valid, in seconds. After that
760 amount of time, the token expires and the delegated credential
761 cannot be used and is removed from the database. The default is
762 4294967 seconds.
763
764 oauth_use_cache: true | false
765 Same as use_cache, but applied to OAuth cache only. If not set, the
766 value from use_cache will be used.
767
768 oom_killer: true | false
769 Enable or disable OOM (out-of-memory) killer. When system memory
770 raises above the limit defined in oom_watermark option, ejabberd
771 triggers OOM killer to terminate most memory consuming Erlang
772 processes. Note that in order to maintain functionality, ejabberd
773 only attempts to kill transient processes, such as those managing
774 client sessions, s2s or database connections. The default value is
775 true.
776
777 oom_queue: Size
778 Trigger OOM killer when some of the running Erlang processes have
779 messages queue above this Size. Note that such processes won’t be
780 killed if oom_killer option is set to false or if oom_watermark is
781 not reached yet.
782
783 oom_watermark: Percent
784 A percent of total system memory consumed at which OOM killer
785 should be activated with some of the processes possibly be killed
786 (see oom_killer option). Later, when memory drops below this
787 Percent, OOM killer is deactivated. The default value is 80
788 percents.
789
790 outgoing_s2s_families: [ipv4 | ipv6, ...]
791 Specify which address families to try, in what order. The default
792 is [ipv4, ipv6] which means it first tries connecting with IPv4, if
793 that fails it tries using IPv6.
794
795 outgoing_s2s_port: 1..65535
796 A port number to use for outgoing s2s connections when the target
797 server doesn’t have an SRV record. The default value is 5269.
798
799 outgoing_s2s_timeout: timeout()
800 The timeout in seconds for outgoing S2S connection attempts. The
801 default value is 10 seconds.
802
803 pam_service: Name
804 This option defines the PAM service name. Refer to the PAM
805 documentation of your operation system for more information. The
806 default value is ejabberd.
807
808 pam_userinfotype: username | jid
809 This option defines what type of information about the user
810 ejabberd provides to the PAM service: only the username, or the
811 user’s JID. Default is username.
812
813 pgsql_users_number_estimate: true | false
814 Whether to use PostgreSQL estimation when counting registered
815 users. The default value is false.
816
817 queue_dir: Directory
818 If queue_type option is set to file, use this Directory to store
819 file queues. The default is to keep queues inside Mnesia directory.
820
821 queue_type: ram | file
822 Default type of queues in ejabberd. Modules may have its own value
823 of the option. The value of ram means that queues will be kept in
824 memory. If value file is set, you may also specify directory in
825 queue_dir option where file queues will be placed. The default
826 value is ram.
827
828 redis_connect_timeout: timeout()
829 A timeout to wait for the connection to be re-established to the
830 Redis server. The default is 1 second.
831
832 redis_db: Number
833 Redis database number. The default is 0.
834
835 redis_password: Password
836 The password to the Redis server. The default is an empty string,
837 i.e. no password.
838
839 redis_pool_size: Number
840 The number of simultaneous connections to the Redis server. The
841 default value is 10.
842
843 redis_port: 1..65535
844 The port where the Redis server is accepting connections. The
845 default is 6379.
846
847 redis_queue_type: ram | file
848 The type of request queue for the Redis server. See description of
849 queue_type option for the explanation. The default value is the
850 value defined in queue_type or ram if the latter is not set.
851
852 redis_server: Hostname
853 A hostname or an IP address of the Redis server. The default is
854 localhost.
855
856 registration_timeout: timeout()
857 This is a global option for module mod_register. It limits the
858 frequency of registrations from a given IP or username. So, a user
859 that tries to register a new account from the same IP address or
860 JID during this time after their previous registration will receive
861 an error with the corresponding explanation. To disable this
862 limitation, set the value to infinity. The default value is 600
863 seconds.
864
865 resource_conflict: setresource | closeold | closenew
866 NOTE: this option is deprecated and may be removed anytime in the
867 future versions. The possible values match exactly the three
868 possibilities described in XMPP Core: section 7.7.2.2. The default
869 value is closeold. If the client uses old Jabber Non-SASL
870 authentication (XEP-0078), then this option is not respected, and
871 the action performed is closeold.
872
873 router_cache_life_time: timeout()
874 Same as cache_life_time, but applied to routing table cache only.
875 If not set, the value from cache_life_time will be used.
876
877 router_cache_missed: true | false
878 Same as cache_missed, but applied to routing table cache only. If
879 not set, the value from cache_missed will be used.
880
881 router_cache_size: pos_integer() | infinity
882 Same as cache_size, but applied to routing table cache only. If not
883 set, the value from cache_size will be used.
884
885 router_db_type: mnesia | sql | redis
886 Database backend to use for routing information. The default value
887 is picked from default_ram_db option, or if it’s not set, mnesia
888 will be used.
889
890 router_use_cache: true | false
891 Same as use_cache, but applied to routing table cache only. If not
892 set, the value from use_cache will be used.
893
894 rpc_timeout: timeout()
895 A timeout for remote function calls between nodes in an ejabberd
896 cluster. You should probably never change this value since those
897 calls are used for internal needs only. The default value is 5
898 seconds.
899
900 s2s_access: Access
901 The access rule to restrict server-to-server connections. The
902 default value is all which means no restrictions are applied.
903
904 s2s_cafile: Path
905 A path to a file with CA root certificates that will be used to
906 authenticate s2s connections. If not set the value of ca_file will
907 be used.
908
909 s2s_ciphers: [Cipher, ...]
910 A list of OpenSSL ciphers to use for s2s connections. The default
911 value is shown in the example below:
912
913 Example:
914
915 s2s_ciphers:
916 - HIGH
917 - "!aNULL"
918 - "!eNULL"
919 - "!3DES"
920 - "@STRENGTH"
921
922 s2s_dhfile: Path
923 Full path to a file containing custom DH parameters to use for s2s
924 connections. Such a file could be created with the command "openssl
925 dhparam -out dh.pem 2048". If this option is not specified,
926 2048-bit MODP Group with 256-bit Prime Order Subgroup will be used
927 as defined in RFC5114 Section 2.3.
928
929 s2s_dns_retries: Number
930 DNS resolving retries. The default value is 2.
931
932 s2s_dns_timeout: timeout()
933 The timeout for DNS resolving. The default value is 10 seconds.
934
935 s2s_max_retry_delay: timeout()
936 The maximum allowed delay for s2s connection retry to connect after
937 a failed connection attempt. The default value is 300 seconds (5
938 minutes).
939
940 s2s_protocol_options: [Option, ...]
941 List of general SSL options to use for s2s connections. These map
942 to OpenSSL’s set_options(). The default value is shown in the
943 example below:
944
945 Example:
946
947 s2s_protocol_options:
948 - no_sslv3
949 - cipher_server_preference
950 - no_compression
951
952 s2s_queue_type: ram | file
953 The type of a queue for s2s packets. See description of queue_type
954 option for the explanation. The default value is the value defined
955 in queue_type or ram if the latter is not set.
956
957 s2s_timeout: timeout()
958 A time to wait before closing an idle s2s connection. The default
959 value is 10 minutes.
960
961 s2s_tls_compression: true | false
962 Whether to enable or disable TLS compression for s2s connections.
963 The default value is false.
964
965 s2s_use_starttls: true | false | optional | required
966 Whether to use STARTTLS for s2s connections. The value of false
967 means STARTTLS is prohibited. The value of true or optional means
968 STARTTLS is enabled but plain connections are still allowed. And
969 the value of required means that only STARTTLS connections are
970 allowed. The default value is false (for historical reasons).
971
972 s2s_zlib: true | false
973 Whether to use zlib compression (as defined in XEP-0138) or not.
974 The default value is false. WARNING: this type of compression is
975 nowadays considered insecure.
976
977 shaper: {ShaperName: Rate}
978 The option defines a set of shapers. Every shaper is assigned a
979 name ShaperName that can be used in other parts of the
980 configuration file, such as shaper_rules option. The shaper itself
981 is defined by its Rate, where Rate stands for the maximum allowed
982 incoming rate in bytes per second. When a connection exceeds this
983 limit, ejabberd stops reading from the socket until the average
984 rate is again below the allowed maximum. In the example below
985 shaper normal limits the traffic speed to 1,000 bytes/sec and
986 shaper fast limits the traffic speed to 50,000 bytes/sec:
987
988 Example:
989
990 shaper:
991 normal: 1000
992 fast: 50000
993
994 shaper_rules: {ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}
995 An entry allowing to declaring shaper to use for matching
996 user/hosts. Semantics is similar to access_rules option, the only
997 difference is that instead using allow or deny, a name of a shaper
998 (defined in shaper option) or a positive number should be used.
999
1000 Example:
1001
1002 shaper_rules:
1003 connections_limit:
1004 10:
1005 user: peter@example.com
1006 100: admin
1007 5: all
1008 download_speed:
1009 fast: admin
1010 slow: anonymous_users
1011 normal: all
1012 log_days: 30
1013
1014 sm_cache_life_time: timeout()
1015 Same as cache_life_time, but applied to client sessions table cache
1016 only. If not set, the value from cache_life_time will be used.
1017
1018 sm_cache_missed: true | false
1019 Same as cache_missed, but applied to client sessions table cache
1020 only. If not set, the value from cache_missed will be used.
1021
1022 sm_cache_size: pos_integer() | infinity
1023 Same as cache_size, but applied to client sessions table cache
1024 only. If not set, the value from cache_size will be used.
1025
1026 sm_db_type: mnesia | sql | redis
1027 Database backend to use for client sessions information. The
1028 default value is picked from default_ram_db option, or if it’s not
1029 set, mnesia will be used.
1030
1031 sm_use_cache: true | false
1032 Same as use_cache, but applied to client sessions table cache only.
1033 If not set, the value from use_cache will be used.
1034
1035 sql_connect_timeout: timeout()
1036 A time to wait for connection to an SQL server to be established.
1037 The default value is 5 seconds.
1038
1039 sql_database: Database
1040 An SQL database name. For SQLite this must be a full path to a
1041 database file. The default value is ejabberd.
1042
1043 sql_keepalive_interval: timeout()
1044 An interval to make a dummy SQL request to keep alive the
1045 connections to the database. There is no default value, so no
1046 keepalive requests are made.
1047
1048 sql_password: Password
1049 The password for SQL authentication. The default is empty string.
1050
1051 sql_pool_size: Size
1052 A number of connections to the SQL server. By default ejabberd
1053 opens 10 connections to the database for each virtual host.
1054 WARNING: for SQLite this value is 1 by default and it’s not
1055 recommended to change it due to potential race conditions.
1056
1057 sql_port: 1..65535
1058 The port where the SQL server is accepting connections. The default
1059 is 3306 for MySQL, 5432 for PostgreSQL and 1433 for MSSQL. The
1060 option has no effect for SQLite.
1061
1062 sql_prepared_statements: true | false
1063 This option is true by default, and is useful to disable prepared
1064 statements. The option is valid for PostgreSQL.
1065
1066 sql_query_timeout: timeout()
1067 A time to wait for an SQL query response. The default value is 60
1068 seconds.
1069
1070 sql_queue_type: ram | file
1071 The type of a request queue for the SQL server. See description of
1072 queue_type option for the explanation. The default value is the
1073 value defined in queue_type or ram if the latter is not set.
1074
1075 sql_server: Host
1076 A hostname or an IP address of the SQL server. The default value is
1077 localhost.
1078
1079 sql_ssl: true | false
1080 Whether to use SSL encrypted connections to the SQL server. The
1081 option is only available for PostgreSQL. The default value is
1082 false.
1083
1084 sql_ssl_cafile: Path
1085 A path to a file with CA root certificates that will be used to
1086 verify SQL connections. Implies sql_ssl and sql_ssl_verify options
1087 are set to true. There is no default which means certificate
1088 verification is disabled.
1089
1090 sql_ssl_certfile: Path
1091 A path to a certificate file that will be used for SSL connections
1092 to the SQL server. Implies sql_ssl option is set to true. There is
1093 no default which means ejabberd won’t provide a client certificate
1094 to the SQL server.
1095
1096 sql_ssl_verify: true | false
1097 Whether to verify SSL connection to the SQL server against CA root
1098 certificates defined in sql_ssl_cafile option. Implies sql_ssl
1099 option is set to true. The default value is false.
1100
1101 sql_start_interval: timeout()
1102 A time to wait before retrying to restore failed SQL connection.
1103 The default value is 30 seconds.
1104
1105 sql_type: mysql | pgsql | sqlite | mssql | odbc
1106 The type of an SQL connection. The default is odbc.
1107
1108 sql_username: Username
1109 A user name for SQL authentication. The default value is ejabberd.
1110
1111 trusted_proxies: all | [Network1, Network2, ...]
1112 Specify what proxies are trusted when an HTTP request contains the
1113 header X-Forwarded-For. You can specify all to allow all proxies,
1114 or specify a list of IPs, possibly with masks. The default value is
1115 an empty list. This allows, if enabled, to be able to know the real
1116 IP of the request, for admin purpose, or security configuration
1117 (for example using mod_fail2ban). IMPORTANT: The proxy MUST be
1118 configured to set the X-Forwarded-For header if you enable this
1119 option as, otherwise, the client can set it itself and as a result
1120 the IP value cannot be trusted for security rules in ejabberd.
1121
1122 use_cache: true | false
1123 Enable or disable cache. The default is true. Several modules have
1124 a similar option; and some core ejabberd parts support similar
1125 options too, see auth_use_cache, oauth_use_cache, router_use_cache,
1126 and sm_use_cache.
1127
1128 validate_stream: true | false
1129 Whether to validate any incoming XML packet according to the
1130 schemas of supported XMPP extensions. WARNING: the validation is
1131 only intended for the use by client developers - don’t enable it in
1132 production environment. The default value is false.
1133
1134 version: string()
1135 The option can be used to set custom ejabberd version, that will be
1136 used by different parts of ejabberd, for example by mod_version
1137 module. The default value is obtained at compile time from the
1138 underlying version control system.
1139
1140 websocket_origin: ignore | URL
1141 This option enables validation for Origin header to protect against
1142 connections from other domains than given in the configuration
1143 file. In this way, the lower layer load balancer can be chosen for
1144 a specific ejabberd implementation while still providing a secure
1145 Websocket connection. The default value is ignore. An example value
1146 of the URL is "https://test.example.org:8081".
1147
1148 websocket_ping_interval: timeout()
1149 Defines time between pings sent by the server to a client
1150 (Websocket level protocol pings are used for this) to keep a
1151 connection active. If the client doesn’t respond to two consecutive
1152 pings, the connection will be assumed as closed. The value of 0 can
1153 be used to disable the feature. This option makes the server
1154 sending pings only for connections using the RFC compliant
1155 protocol. For older style connections the server expects that
1156 whitespace pings would be used for this purpose. The default value
1157 is 60 seconds.
1158
1159 websocket_timeout: timeout()
1160 Amount of time without any communication after which the connection
1161 would be closed. The default value is 300 seconds.
1162
1164 This section describes options of all modules in ejabberd 20.04
1165
1166 mod_adhoc
1167 This module implements XEP-0050: Ad-Hoc Commands. It’s an auxiliary
1168 module and is only needed by some of the other modules.
1169
1170 Available options:
1171 report_commands_node: true | false
1172 Provide the Commands item in the Service Discovery. Default
1173 value: false.
1174
1175 mod_admin_extra
1176 This module provides additional administrative commands.
1177
1178 Details for some commands:
1179
1180 · ban-acount: This command kicks all the connected sessions of the
1181 account from the server. It also changes their password to a
1182 randomly generated one, so they can’t login anymore unless a server
1183 administrator changes their password again. It is possible to
1184 define the reason of the ban. The new password also includes the
1185 reason and the date and time of the ban. See an example below.
1186
1187 · pushroster: (and pushroster-all) The roster file must be placed, if
1188 using Windows, on the directory where you installed ejabberd:
1189 C:/Program Files/ejabberd or similar. If you use other Operating
1190 System, place the file on the same directory where the .beam files
1191 are installed. See below an example roster file.
1192
1193 · srg-create: If you want to put a group Name with blankspaces, use
1194 the characters "' and '" to define when the Name starts and ends.
1195 See an example below.
1196
1197 Available options:
1198 module_resource: Resource
1199 Indicate the resource that the XMPP stanzas must use in the
1200 FROM or TO JIDs. This is only useful in the get_vcard* and
1201 set_vcard* commands. The default value is mod_admin_extra.
1202
1203 Examples:
1204 With this configuration, vCards can only be modified with
1205 mod_admin_extra commands:
1206
1207 acl:
1208 adminextraresource:
1209 - resource: "modadminextraf8x,31ad"
1210 access_rules:
1211 vcard_set:
1212 - allow: adminextraresource
1213 modules:
1214 mod_admin_extra:
1215 module_resource: "modadminextraf8x,31ad"
1216 mod_vcard:
1217 access_set: vcard_set
1218
1219 Content of roster file for pushroster command:
1220
1221 [{<<"bob">>, <<"example.org">>, <<"workers">>, <<"Bob">>},
1222 {<<"mart">>, <<"example.org">>, <<"workers">>, <<"Mart">>},
1223 {<<"Rich">>, <<"example.org">>, <<"bosses">>, <<"Rich">>}].
1224
1225 With this call, the sessions of the local account which JID is
1226 boby@example.org will be kicked, and its password will be set to
1227 something like
1228 BANNED_ACCOUNT—20080425T21:45:07—2176635—Spammed_rooms
1229
1230 ejabberdctl vhost example.org ban-account boby "Spammed rooms"
1231
1232 Call to srg-create using double-quotes and single-quotes:
1233
1234 ejabberdctl srg-create g1 example.org "'Group number 1'" this_is_g1 g1
1235
1236 mod_admin_update_sql
1237 This module can be used to update existing SQL database from old to new
1238 schema. When the module is loaded use update_sql ejabberdctl command.
1239
1240 The module has no options.
1241
1242 mod_announce
1243 This module enables configured users to broadcast announcements and to
1244 set the message of the day (MOTD). Configured users can perform these
1245 actions with an XMPP client either using Ad-hoc Commands or sending
1246 messages to specific JIDs.
1247
1248 Note that this module can be resource intensive on large deployments as
1249 it may broadcast a lot of messages. This module should be disabled for
1250 instances of ejabberd with hundreds of thousands users.
1251
1252 The Ad-hoc Commands are listed in the Server Discovery. For this
1253 feature to work, mod_adhoc must be enabled.
1254
1255 The specific JIDs where messages can be sent are listed below. The
1256 first JID in each entry will apply only to the specified virtual host
1257 example.org, while the JID between brackets will apply to all virtual
1258 hosts in ejabberd:
1259
1260 · example.org/announce/all (example.org/announce/all-hosts/all):: The
1261 message is sent to all registered users. If the user is online and
1262 connected to several resources, only the resource with the highest
1263 priority will receive the message. If the registered user is not
1264 connected, the message will be stored offline in assumption that
1265 offline storage (see mod_offline) is enabled.
1266
1267 · example.org/announce/online
1268 (example.org/announce/all-hosts/online):: The message is sent to
1269 all connected users. If the user is online and connected to several
1270 resources, all resources will receive the message.
1271
1272 · example.org/announce/motd (example.org/announce/all-hosts/motd)::
1273 The message is set as the message of the day (MOTD) and is sent to
1274 users when they login. In addition the message is sent to all
1275 connected users (similar to announce/online).
1276
1277 · example.org/announce/motd/update
1278 (example.org/announce/all-hosts/motd/update):: The message is set
1279 as message of the day (MOTD) and is sent to users when they login.
1280 The message is not sent to any currently connected user.
1281
1282 · example.org/announce/motd/delete
1283 (example.org/announce/all-hosts/motd/delete):: Any message sent to
1284 this JID removes the existing message of the day (MOTD).
1285
1286 Available options:
1287 access: AccessName
1288 This option specifies who is allowed to send announcements and
1289 to set the message of the day. The default value is none (i.e.
1290 nobody is able to send such messages).
1291
1292 cache_life_time: timeout()
1293 Same as top-level cache_life_time option, but applied to this
1294 module only.
1295
1296 cache_missed: true | false
1297 Same as top-level cache_missed option, but applied to this
1298 module only.
1299
1300 cache_size: pos_integer() | infinity
1301 Same as top-level cache_size option, but applied to this module
1302 only.
1303
1304 db_type: mnesia | sql
1305 Same as top-level default_db option, but applied to this module
1306 only.
1307
1308 use_cache: true | false
1309 Same as top-level use_cache option, but applied to this module
1310 only.
1311
1312 mod_avatar
1313 The purpose of the module is to cope with legacy and modern XMPP
1314 clients posting avatars. The process is described in XEP-0398: User
1315 Avatar to vCard-Based Avatars Conversion.
1316
1317 Also, the module supports conversion between avatar image formats on
1318 the fly.
1319
1320 The module depends on mod_vcard, mod_vcard_xupdate and mod_pubsub.
1321
1322 Available options:
1323 convert: {From: To}
1324 Defines image convertion rules: the format in From will be
1325 converted to format in To. The value of From can also be
1326 default, which is match-all rule. NOTE: the list of supported
1327 formats is detected at compile time depending on the image
1328 libraries installed in the system.
1329
1330 Example:
1331
1332 convert:
1333 webp: jpg
1334 default: png
1335
1336 rate_limit: Number
1337 Limit any given JID by the number of avatars it is able to
1338 convert per minute. This is to protect the server from image
1339 convertion DoS. The default value is 10.
1340
1341 mod_block_strangers
1342 This module allows to block/log messages coming from an unknown entity.
1343 If a writing entity is not in your roster, you can let this module drop
1344 and/or log the message. By default you’ll just not receive message from
1345 that entity. Enable this module if you want to drop SPAM messages.
1346
1347 Available options:
1348 access: AccessName
1349 The option is supposed to be used when allow_local_users and
1350 allow_transports are not enough. It’s an ACL where deny means
1351 the message will be rejected (or a CAPTCHA would be generated
1352 for a presence, if configured), and allow means the sender is
1353 whitelisted and the stanza will pass through. The default value
1354 is none, which means nothing is whitelisted.
1355
1356 allow_local_users: true | false
1357 This option specifies if strangers from the same local host
1358 should be accepted or not. The default value is true.
1359
1360 allow_transports: true | false
1361 If set to true and some server’s JID is in user’s roster, then
1362 messages from any user of this server are accepted even if no
1363 subscription present. The default value is true.
1364
1365 captcha: true | false
1366 Whether to generate CAPTCHA or not in response to messages from
1367 strangers. See also section CAPTCHA of the Configuration Guide.
1368 The default value is false.
1369
1370 drop: true | false
1371 This option specifies if strangers messages should be dropped
1372 or not. The default value is true.
1373
1374 log: true | false
1375 This option specifies if strangers' messages should be logged
1376 (as info message) in ejabberd.log. The default value is false.
1377
1378 mod_blocking
1379 The module implements XEP-0191: Blocking Command.
1380
1381 This module depends on mod_privacy where all the configuration is
1382 performed.
1383
1384 The module has no options.
1385
1386 mod_bosh
1387 This module implements XMPP over BOSH as defined in XEP-0124 and
1388 XEP-0206. BOSH stands for Bidirectional-streams Over Synchronous HTTP.
1389 It makes it possible to simulate long lived connections required by
1390 XMPP over the HTTP protocol. In practice, this module makes it possible
1391 to use XMPP in a browser without Websocket support and more generally
1392 to have a way to use XMPP while having to get through an HTTP proxy.
1393
1394 Available options:
1395 cache_life_time: timeout()
1396 Same as top-level cache_life_time option, but applied to this
1397 module only.
1398
1399 cache_missed: true | false
1400 Same as top-level cache_missed option, but applied to this
1401 module only.
1402
1403 cache_size: pos_integer() | infinity
1404 Same as top-level cache_size option, but applied to this module
1405 only.
1406
1407 json: true | false
1408 This option has no effect.
1409
1410 max_concat: pos_integer() | infinity
1411 This option limits the number of stanzas that the server will
1412 send in a single bosh request. The default value is unlimited.
1413
1414 max_inactivity: timeout()
1415 The option defines the maximum inactivity period. The default
1416 value is 30 seconds.
1417
1418 max_pause: pos_integer()
1419 Indicate the maximum length of a temporary session pause (in
1420 seconds) that a client can request. The default value is 120.
1421
1422 prebind: true | false
1423 If enabled, the client can create the session without going
1424 through authentication. Basically, it creates a new session
1425 with anonymous authentication. The default value is false.
1426
1427 queue_type: ram | file
1428 Same as top-level queue_type option, but applied to this module
1429 only.
1430
1431 ram_db_type: mnesia | sql | redis
1432 Same as default_ram_db but applied to this module only.
1433
1434 use_cache: true | false
1435 Same as top-level use_cache option, but applied to this module
1436 only.
1437
1438 Example:
1439 listen:
1440 -
1441 port: 5222
1442 module: ejabberd_c2s
1443 -
1444 port: 5443
1445 module: ejabberd_http
1446 request_handlers:
1447 /bosh: mod_bosh
1448
1449 modules:
1450 mod_bosh: {}
1451
1452 mod_caps
1453 This module implements XEP-0115: Entity Capabilities. The main purpose
1454 of the module is to provide PEP functionality (see mod_pubsub).
1455
1456 Available options:
1457 cache_life_time: timeout()
1458 Same as top-level cache_life_time option, but applied to this
1459 module only.
1460
1461 cache_missed: true | false
1462 Same as top-level cache_missed option, but applied to this
1463 module only.
1464
1465 cache_size: pos_integer() | infinity
1466 Same as top-level cache_size option, but applied to this module
1467 only.
1468
1469 db_type: mnesia | sql
1470 Same as top-level default_db option, but applied to this module
1471 only.
1472
1473 use_cache: true | false
1474 Same as top-level use_cache option, but applied to this module
1475 only.
1476
1477 mod_carboncopy
1478 The module implements XEP-0280: Message Carbons. The module broadcasts
1479 messages on all connected user resources (devices).
1480
1481 The module has no options.
1482
1483 mod_client_state
1484 This module allows for queueing certain types of stanzas when a client
1485 indicates that the user is not actively using the client right now (see
1486 XEP-0352: Client State Indication). This can save bandwidth and
1487 resources.
1488
1489 A stanza is dropped from the queue if it’s effectively obsoleted by a
1490 new one (e.g., a new presence stanza would replace an old one from the
1491 same client). The queue is flushed if a stanza arrives that won’t be
1492 queued, or if the queue size reaches a certain limit (currently 100
1493 stanzas), or if the client becomes active again.
1494
1495 Available options:
1496 queue_chat_states: true | false
1497 Queue "standalone" chat state notifications (as defined in
1498 XEP-0085: Chat State Notifications) while a client indicates
1499 inactivity. The default value is true.
1500
1501 queue_pep: true | false
1502 Queue PEP notifications while a client is inactive. When the
1503 queue is flushed, only the most recent notification of a given
1504 PEP node is delivered. The default value is true.
1505
1506 queue_presence: true | false
1507 While a client is inactive, queue presence stanzas that
1508 indicate (un)availability. The default value is true.
1509
1510 mod_configure
1511 The module provides server configuration functionality via XEP-0050:
1512 Ad-Hoc Commands. This module requires mod_adhoc to be loaded.
1513
1514 The module has no options.
1515
1516 mod_delegation
1517 This module is an implementation of XEP-0355: Namespace Delegation.
1518 Only admin mode has been implemented by now. Namespace delegation
1519 allows external services to handle IQ using specific namespace. This
1520 may be applied for external PEP service.
1521
1522 Warning
1523 Security issue: Namespace delegation gives components access to
1524 sensitive data, so permission should be granted carefully, only if
1525 you trust the component.
1526
1527 Note
1528 This module is complementary to mod_privilege but can also be used
1529 separately.
1530
1531 Available options:
1532 namespaces: {Namespace: Options}
1533 If you want to delegate namespaces to a component, specify them
1534 in this option, and associate them to an access rule. The
1535 Options are:
1536
1537 access: AccessName
1538 The option defines which components are allowed for
1539 namespace delegation. The default value is none.
1540
1541 filtering: Attributes
1542 The list of attributes. Currently not used.
1543
1544 Examples:
1545 Make sure you do not delegate the same namespace to several
1546 services at the same time. As in the example provided later, to
1547 have the sat-pubsub.example.org component perform correctly disable
1548 the mod_pubsub module.
1549
1550 access_rules:
1551 external_pubsub:
1552 allow: external_component
1553 external_mam:
1554 allow: external_component
1555
1556 acl:
1557 external_component:
1558 server: sat-pubsub.example.org
1559
1560 modules:
1561 ...
1562 mod_delegation:
1563 namespaces:
1564 urn:xmpp:mam:1:
1565 access: external_mam
1566 http://jabber.org/protocol/pubsub:
1567 access: external_pubsub
1568
1569 mod_disco
1570 This module adds support for XEP-0030: Service Discovery. With this
1571 module enabled, services on your server can be discovered by XMPP
1572 clients.
1573
1574 Available options:
1575 extra_domains: [Domain, ...]
1576 With this option, you can specify a list of extra domains that
1577 are added to the Service Discovery item list. The default value
1578 is an empty list.
1579
1580 name: Name
1581 A name of the server in the Service Discovery. This will only
1582 be displayed by special XMPP clients. The default value is
1583 ejabberd.
1584
1585 server_info: [Info, ...]
1586 Specify additional information about the server, as described
1587 in XEP-0157: Contact Addresses for XMPP Services. Every Info
1588 element in the list is constructed from the following options:
1589
1590 modules: all | [Module, ...]
1591 The value can be the keyword all, in which case the
1592 information is reported in all the services, or a list of
1593 ejabberd modules, in which case the information is only
1594 specified for the services provided by those modules.
1595
1596 name: Name
1597 Any arbitrary name of the contact.
1598
1599 urls: [URI, ...]
1600 A list of contact URIs, such as HTTP URLs, XMPP URIs and so
1601 on.
1602
1603 Example:
1604
1605 server_info:
1606 -
1607 modules: all
1608 name: abuse-addresses
1609 urls: [mailto:abuse@shakespeare.lit]
1610 -
1611 modules: [mod_muc]
1612 name: "Web chatroom logs"
1613 urls: [http://www.example.org/muc-logs]
1614 -
1615 modules: [mod_disco]
1616 name: feedback-addresses
1617 urls:
1618 - http://shakespeare.lit/feedback.php
1619 - mailto:feedback@shakespeare.lit
1620 - xmpp:feedback@shakespeare.lit
1621 -
1622 modules:
1623 - mod_disco
1624 - mod_vcard
1625 name: admin-addresses
1626 urls:
1627 - mailto:xmpp@shakespeare.lit
1628 - xmpp:admins@shakespeare.lit
1629
1630 mod_fail2ban
1631 The module bans IPs that show the malicious signs. Currently only C2S
1632 authentication failures are detected.
1633
1634 Unlike the standalone program, mod_fail2ban clears the record of
1635 authentication failures after some time since the first failure or on a
1636 successful authentication. It also does not simply block network
1637 traffic, but provides the client with a descriptive error message.
1638
1639 Warning
1640 You should not use this module behind a proxy or load balancer.
1641 ejabberd will see the failures as coming from the load balancer
1642 and, when the threshold of auth failures is reached, will reject
1643 all connections coming from the load balancer. You can lock all
1644 your user base out of ejabberd when using this module behind a
1645 proxy.
1646
1647 Available options:
1648 access: AccessName
1649 Specify an access rule for whitelisting IP addresses or
1650 networks. If the rule returns allow for a given IP address,
1651 that address will never be banned. The AccessName should be of
1652 type ip. The default value is none.
1653
1654 c2s_auth_ban_lifetime: timeout()
1655 The lifetime of the IP ban caused by too many C2S
1656 authentication failures. The default value is 1 hour.
1657
1658 c2s_max_auth_failures: Number
1659 The number of C2S authentication failures to trigger the IP
1660 ban. The default value is 20.
1661
1662 mod_http_api
1663 This module provides a ReST API to call ejabberd commands using JSON
1664 data.
1665
1666 To use this module, in addition to adding it to the modules section,
1667 you must also add it to request_handlers of some listener.
1668
1669 To use a specific API version N, when defining the URL path in the
1670 request_handlers, add a vN. For example: /api/v2: mod_http_api
1671
1672 To run a command, send a POST request to the corresponding URL:
1673 http://localhost:5280/api/<command_name>
1674
1675 The module has no options.
1676
1677 mod_http_fileserver
1678 This simple module serves files from the local disk over HTTP.
1679
1680 Available options:
1681 accesslog: Path
1682 File to log accesses using an Apache-like format. No log will
1683 be recorded if this option is not specified.
1684
1685 content_types: {Extension: Type}
1686 Specify mappings of extension to content type. There are
1687 several content types already defined. With this option you can
1688 add new definitions or modify existing ones. The default values
1689 are:
1690
1691 Example:
1692
1693 content_types:
1694 .css: text/css
1695 .gif: image/gif
1696 .html: text/html
1697 .jar: application/java-archive
1698 .jpeg: image/jpeg
1699 .jpg: image/jpeg
1700 .js: text/javascript
1701 .png: image/png
1702 .svg: image/svg+xml
1703 .txt: text/plain
1704 .xml: application/xml
1705 .xpi: application/x-xpinstall
1706 .xul: application/vnd.mozilla.xul+xml
1707
1708 custom_headers: {Name: Value}
1709 Indicate custom HTTP headers to be included in all responses.
1710 There are no custom headers by default.
1711
1712 default_content_type: Type
1713 Specify the content type to use for unknown extensions. The
1714 default value is application/octet-stream.
1715
1716 directory_indices: [Index, ...]
1717 Indicate one or more directory index files, similarly to
1718 Apache’s DirectoryIndex variable. When an HTTP request hits a
1719 directory instead of a regular file, those directory indices
1720 are looked in order, and the first one found is returned. The
1721 default value is an empty list.
1722
1723 docroot: Path
1724 Directory to serve the files from. This is a mandatory option.
1725
1726 must_authenticate_with: [{Username, Hostname}, ...]
1727 List of accounts that are allowed to use this service. Default
1728 value: [].
1729
1730 Examples:
1731 This example configuration will serve the files from the local
1732 directory /var/www in the address
1733 http://example.org:5280/pub/archive/. In this example a new content
1734 type ogg is defined, png is redefined, and jpg definition is
1735 deleted:
1736
1737 listen:
1738 ...
1739 -
1740 port: 5280
1741 module: ejabberd_http
1742 request_handlers:
1743 ...
1744 /pub/archive: mod_http_fileserver
1745 ...
1746 ...
1747
1748 modules:
1749 ...
1750 mod_http_fileserver:
1751 docroot: /var/www
1752 accesslog: /var/log/ejabberd/access.log
1753 directory_indices:
1754 - index.html
1755 - main.htm
1756 custom_headers:
1757 X-Powered-By: Erlang/OTP
1758 X-Fry: "It's a widely-believed fact!"
1759 content_types:
1760 .ogg: audio/ogg
1761 .png: image/png
1762 default_content_type: text/html
1763 ...
1764
1765 mod_http_upload
1766 This module allows for requesting permissions to upload a file via HTTP
1767 as described in XEP-0363: HTTP File Upload. If the request is accepted,
1768 the client receives a URL for uploading the file and another URL from
1769 which that file can later be downloaded.
1770
1771 In order to use this module, it must be configured as a request_handler
1772 for ejabberd_http listener.
1773
1774 Available options:
1775 access: AccessName
1776 This option defines the access rule to limit who is permitted
1777 to use the HTTP upload service. The default value is local. If
1778 no access rule of that name exists, no user will be allowed to
1779 use the service.
1780
1781 custom_headers: {Name: Value}
1782 This option specifies additional header fields to be included
1783 in all HTTP responses. By default no custom headers are
1784 included.
1785
1786 dir_mode: Permission
1787 This option defines the permission bits of the docroot
1788 directory and any directories created during file uploads. The
1789 bits are specified as an octal number (see the chmod(1) manual
1790 page) within double quotes. For example: "0755". The default is
1791 undefined, which means no explicit permissions will be set.
1792
1793 docroot: Path
1794 Uploaded files are stored below the directory specified (as an
1795 absolute path) with this option. The keyword @HOME@ is replaced
1796 with the home directory of the user running ejabberd, and the
1797 keyword @HOST@ with the virtual host name. The default value is
1798 "@HOME@/upload".
1799
1800 external_secret: Text
1801 This option makes it possible to offload all HTTP Upload
1802 processing to a separate HTTP server. Both ejabberd and the
1803 HTTP server should share this secret and behave exactly as
1804 described at Prosody’s mod_http_upload_external in the
1805 Implementation section. There is no default value.
1806
1807 file_mode: Permission
1808 This option defines the permission bits of uploaded files. The
1809 bits are specified as an octal number (see the chmod(1) manual
1810 page) within double quotes. For example: "0644". The default is
1811 undefined, which means no explicit permissions will be set.
1812
1813 get_url: URL
1814 This option specifies the initial part of the GET URLs used for
1815 downloading the files. By default, it is set to the same value
1816 as put_url. The keyword @HOST@ is replaced with the virtual
1817 host name. NOTE: if GET requests are handled by
1818 mod_http_upload, the get_url must match the put_url. Setting it
1819 to a different value only makes sense if an external web server
1820 or mod_http_fileserver is used to serve the uploaded files.
1821
1822 host
1823 Deprecated. Use hosts instead.
1824
1825 hosts: [Host, ...]
1826 This option defines the Jabber IDs of the service. If the hosts
1827 option is not specified, the only Jabber ID will be the
1828 hostname of the virtual host with the prefix "upload.". The
1829 keyword @HOST@ is replaced with the real virtual host name.
1830
1831 jid_in_url: node | sha1
1832 When this option is set to node, the node identifier of the
1833 user’s JID (i.e., the user name) is included in the GET and PUT
1834 URLs generated by mod_http_upload. Otherwise, a SHA-1 hash of
1835 the user’s bare JID is included instead. The default value is
1836 sha1.
1837
1838 max_size: Size
1839 This option limits the acceptable file size. Either a number of
1840 bytes (larger than zero) or infinity must be specified. The
1841 default value is 104857600.
1842
1843 name: Name
1844 A name of the service in the Service Discovery. This will only
1845 be displayed by special XMPP clients. The default value is
1846 "HTTP File Upload".
1847
1848 put_url: URL
1849 This option specifies the initial part of the PUT URLs used for
1850 file uploads. The keyword @HOST@ is replaced with the virtual
1851 host name. NOTE: different virtual hosts cannot use the same
1852 PUT URL. The default value is "https://@HOST@:5443".
1853
1854 rm_on_unregister: true | false
1855 This option specifies whether files uploaded by a user should
1856 be removed when that user is unregistered. The default value is
1857 true.
1858
1859 secret_length: Length
1860 This option defines the length of the random string included in
1861 the GET and PUT URLs generated by mod_http_upload. The minimum
1862 length is 8 characters, but it is recommended to choose a
1863 larger value. The default value is 40.
1864
1865 service_url
1866 Deprecated.
1867
1868 thumbnail: true | false
1869 This option specifies whether ejabberd should create thumbnails
1870 of uploaded images. If a thumbnail is created, a <thumbnail/>
1871 element that contains the download <uri/> and some metadata is
1872 returned with the PUT response. The default value is false.
1873
1874 vcard: vCard
1875 A custom vCard of the service that will be displayed by some
1876 XMPP clients in Service Discovery. The value of vCard is a YAML
1877 map constructed from an XML representation of vCard. Since the
1878 representation has no attributes, the mapping is
1879 straightforward.
1880
1881 For example, the following XML representation of vCard:
1882
1883 <vCard xmlns='vcard-temp'>
1884 <FN>Conferences</FN>
1885 <ADR>
1886 <WORK/>
1887 <STREET>Elm Street</STREET>
1888 </ADR>
1889 </vCard>
1890
1891 will be translated to:
1892
1893 vcard:
1894 fn: Conferences
1895 adr:
1896 -
1897 work: true
1898 street: Elm Street
1899
1900 Example:
1901 listen:
1902 ...
1903 -
1904 port: 5443
1905 module: ejabberd_http
1906 tls: true
1907 request_handlers:
1908 ...
1909 /upload: mod_http_upload
1910 ...
1911 ...
1912
1913 modules:
1914 ...
1915 mod_http_upload:
1916 docroot: /ejabberd/upload
1917 put_url: "https://@HOST@:5443/upload"
1918 ...
1919
1920 mod_http_upload_quota
1921 This module adds quota support for mod_http_upload.
1922
1923 This module depends on mod_http_upload.
1924
1925 Available options:
1926 access_hard_quota: AccessName
1927 This option defines which access rule is used to specify the
1928 "hard quota" for the matching JIDs. That rule must yield a
1929 positive number for any JID that is supposed to have a quota
1930 limit. This is the number of megabytes a corresponding user may
1931 upload. When this threshold is exceeded, ejabberd deletes the
1932 oldest files uploaded by that user until their disk usage
1933 equals or falls below the specified soft quota (see
1934 access_soft_quota). The default value is hard_upload_quota.
1935
1936 access_soft_quota: AccessName
1937 This option defines which access rule is used to specify the
1938 "soft quota" for the matching JIDs. That rule must yield a
1939 positive number of megabytes for any JID that is supposed to
1940 have a quota limit. See the description of the
1941 access_hard_quota option for details. The default value is
1942 soft_upload_quota.
1943
1944 max_days: Days
1945 If a number larger than zero is specified, any files (and
1946 directories) older than this number of days are removed from
1947 the subdirectories of the docroot directory, once per day. The
1948 default value is infinity.
1949
1950 Examples:
1951 Please note that it’s not necessary to specify the
1952 access_hard_quota and access_soft_quota options in order to use the
1953 quota feature. You can stick to the default names and just specify
1954 access rules such as those in this example:
1955
1956 shaper_rules:
1957 ...
1958 soft_upload_quota:
1959 1000: all # MiB
1960 hard_upload_quota:
1961 1100: all # MiB
1962 ...
1963
1964 modules:
1965 ...
1966 mod_http_upload: {}
1967 mod_http_upload_quota:
1968 max_days: 100
1969 ...
1970
1971 mod_jidprep
1972 This module allows XMPP clients to ask the server to normalize a JID as
1973 per the rules specified in RFC 6122: XMPP Address Format. This might be
1974 useful for clients in certain constrained environments, or for testing
1975 purposes.
1976
1977 Available options:
1978 access: AccessName
1979 This option defines which access rule will be used to control
1980 who is allowed to use this service. The default value is local.
1981
1982 mod_last
1983 This module adds support for XEP-0012: Last Activity. It can be used to
1984 discover when a disconnected user last accessed the server, to know
1985 when a connected user was last active on the server, or to query the
1986 uptime of the ejabberd server.
1987
1988 Available options:
1989 cache_life_time: timeout()
1990 Same as top-level cache_life_time option, but applied to this
1991 module only.
1992
1993 cache_missed: true | false
1994 Same as top-level cache_missed option, but applied to this
1995 module only.
1996
1997 cache_size: pos_integer() | infinity
1998 Same as top-level cache_size option, but applied to this module
1999 only.
2000
2001 db_type: mnesia | sql
2002 Same as top-level default_db option, but applied to this module
2003 only.
2004
2005 use_cache: true | false
2006 Same as top-level use_cache option, but applied to this module
2007 only.
2008
2009 mod_legacy_auth
2010 The module implements XEP-0078: Non-SASL Authentication.
2011
2012 Note
2013 This type of authentication was obsoleted in 2008 and you unlikely
2014 need this module unless you have something like outdated Jabber
2015 bots.
2016
2017 The module has no options.
2018
2019 mod_mam
2020 This module implements XEP-0313: Message Archive Management. Compatible
2021 XMPP clients can use it to store their chat history on the server.
2022
2023 Available options:
2024 access_preferences: AccessName
2025 This access rule defines who is allowed to modify the MAM
2026 preferences. The default value is all.
2027
2028 assume_mam_usage: true | false
2029 This option determines how ejabberd’s stream management code
2030 (see mod_stream_mgmt) handles unacknowledged messages when the
2031 connection is lost. Usually, such messages are either bounced
2032 or resent. However, neither is done for messages that were
2033 stored in the user’s MAM archive if this option is set to true.
2034 In this case, ejabberd assumes those messages will be retrieved
2035 from the archive. The default value is false.
2036
2037 cache_life_time: timeout()
2038 Same as top-level cache_life_time option, but applied to this
2039 module only.
2040
2041 cache_missed: true | false
2042 Same as top-level cache_missed option, but applied to this
2043 module only.
2044
2045 cache_size: pos_integer() | infinity
2046 Same as top-level cache_size option, but applied to this module
2047 only.
2048
2049 clear_archive_on_room_destroy: true | false
2050 Whether to destroy message archive of a room (see mod_muc) when
2051 it gets destroyed. The default value is true.
2052
2053 compress_xml: true | false
2054 When enabled, new messages added to archives are compressed
2055 using a custom compression algorithm. This feature works only
2056 with SQL backends. The default value is false.
2057
2058 db_type: mnesia | sql
2059 Same as top-level default_db option, but applied to this module
2060 only.
2061
2062 default: always | never | roster
2063 The option defines default policy for chat history. When always
2064 is set every chat message is stored. With roster only chat
2065 history with contacts from user’s roster is stored. And never
2066 fully disables chat history. Note that a client can change its
2067 policy via protocol commands. The default value is never.
2068
2069 request_activates_archiving: true | false
2070 If the value is true, no messages are stored for a user until
2071 their client issue a MAM request, regardless of the value of
2072 the default option. Once the server received a request, that
2073 user’s messages are archived as usual. The default value is
2074 false.
2075
2076 use_cache: true | false
2077 Same as top-level use_cache option, but applied to this module
2078 only.
2079
2080 user_mucsub_from_muc_archive: true | false
2081 When this option is disabled, for each individual subscriber a
2082 separa mucsub message is stored. With this option enabled, when
2083 a user fetches archive virtual mucsub, messages are generated
2084 from muc archives. The default value is false.
2085
2086 mod_metrics
2087 This module sends events to external backend (by now only grapherl is
2088 supported). Supported events are:
2089
2090 · sm_register_connection
2091
2092 · sm_remove_connection
2093
2094 · user_send_packet
2095
2096 · user_receive_packet
2097
2098 · s2s_send_packet
2099
2100 · s2s_receive_packet
2101
2102 · register_user
2103
2104 · remove_user
2105
2106 · offline_message
2107
2108 When enabled, every call to these hooks triggers a counter event to be
2109 sent to the external backend.
2110
2111 Available options:
2112 ip: IPv4Address
2113 IPv4 address where the backend is located. The default value is
2114 127.0.0.1.
2115
2116 port: Port
2117 An internet port number at which the backend is listening for
2118 incoming connections/packets. The default value is 11111.
2119
2120 mod_mix
2121 This module is an experimental implementation of XEP-0369: Mediated
2122 Information eXchange (MIX). MIX support was added in ejabberd 16.03 as
2123 an experimental feature, updated in 19.02, and is not yet ready to use
2124 in production. It’s asserted that the MIX protocol is going to replace
2125 the MUC protocol in the future (see mod_muc).
2126
2127 To learn more about how to use that feature, you can refer to our
2128 tutorial: Getting started with XEP-0369: Mediated Information eXchange
2129 (MIX) v0.1.
2130
2131 The module depends on mod_mam.
2132
2133 Available options:
2134 access_create: AccessName
2135 An access rule to control MIX channels creations. The default
2136 value is all.
2137
2138 db_type: mnesia | sql
2139 Same as top-level default_db option, but applied to this module
2140 only.
2141
2142 host
2143 Deprecated. Use hosts instead.
2144
2145 hosts: [Host, ...]
2146 This option defines the Jabber IDs of the service. If the hosts
2147 option is not specified, the only Jabber ID will be the
2148 hostname of the virtual host with the prefix "mix.". The
2149 keyword @HOST@ is replaced with the real virtual host name.
2150
2151 name: Name
2152 A name of the service in the Service Discovery. This will only
2153 be displayed by special XMPP clients. The default value is
2154 Channels.
2155
2156 mod_mix_pam
2157 This module implements XEP-0405: Mediated Information eXchange (MIX):
2158 Participant Server Requirements. The module is needed if MIX compatible
2159 clients on your server are going to join MIX channels (either on your
2160 server or on any remote servers).
2161
2162 Note
2163 mod_mix is not required for this module to work, however, without
2164 mod_mix_pam the MIX functionality of your local XMPP clients will
2165 be impaired.
2166
2167 Available options:
2168 cache_life_time: timeout()
2169 Same as top-level cache_life_time option, but applied to this
2170 module only.
2171
2172 cache_missed: true | false
2173 Same as top-level cache_missed option, but applied to this
2174 module only.
2175
2176 cache_size: pos_integer() | infinity
2177 Same as top-level cache_size option, but applied to this module
2178 only.
2179
2180 db_type: mnesia | sql
2181 Same as top-level default_db option, but applied to this module
2182 only.
2183
2184 use_cache: true | false
2185 Same as top-level use_cache option, but applied to this module
2186 only.
2187
2188 mod_mqtt
2189 This module adds support for the MQTT protocol version 3.1.1 and 5.0.
2190 Remember to configure mod_mqtt in modules and listen sections.
2191
2192 Available options:
2193 access_publish: {TopicFilter: AccessName}
2194 Access rules to restrict access to topics for publishers. By
2195 default there are no restrictions.
2196
2197 access_subscribe: {TopicFilter: AccessName}
2198 Access rules to restrict access to topics for subscribers. By
2199 default there are no restrictions.
2200
2201 cache_life_time: timeout()
2202 Same as top-level cache_life_time option, but applied to this
2203 module only.
2204
2205 cache_missed: true | false
2206 Same as top-level cache_missed option, but applied to this
2207 module only.
2208
2209 cache_size: pos_integer() | infinity
2210 Same as top-level cache_size option, but applied to this module
2211 only.
2212
2213 db_type: mnesia | sql
2214 Same as top-level default_db option, but applied to this module
2215 only.
2216
2217 match_retained_limit: pos_integer() | infinity
2218 The option limits the number of retained messages returned to a
2219 client when it subscribes to some topic filter. The default
2220 value is 1000.
2221
2222 max_queue: Size
2223 Maximum queue size for outgoing packets. The default value is
2224 5000.
2225
2226 max_topic_aliases: 0..65535
2227 The maximum number of aliases a client is able to associate
2228 with the topics. The default value is 100.
2229
2230 max_topic_depth: Depth
2231 The maximum topic depth, i.e. the number of slashes (/) in the
2232 topic. The default value is 8.
2233
2234 queue_type: ram | file
2235 Same as top-level queue_type option, but applied to this module
2236 only.
2237
2238 ram_db_type: mnesia
2239 Same as top-level default_ram_db option, but applied to this
2240 module only.
2241
2242 session_expiry: timeout()
2243 The option specifies how long to wait for an MQTT session
2244 resumption. When 0 is set, the session gets destroyed when the
2245 underlying client connection is closed. The default value is 5
2246 minutes.
2247
2248 use_cache: true | false
2249 Same as top-level use_cache option, but applied to this module
2250 only.
2251
2252 mod_muc
2253 This module provides support for XEP-0045: Multi-User Chat. Users can
2254 discover existing rooms, join or create them. Occupants of a room can
2255 chat in public or have private chats.
2256
2257 The MUC service allows any Jabber ID to register a nickname, so nobody
2258 else can use that nickname in any room in the MUC service. To register
2259 a nickname, open the Service Discovery in your XMPP client and register
2260 in the MUC service.
2261
2262 This module supports clustering and load balancing. One module can be
2263 started per cluster node. Rooms are distributed at creation time on all
2264 available MUC module instances. The multi-user chat module is clustered
2265 but the rooms themselves are not clustered nor fault-tolerant: if the
2266 node managing a set of rooms goes down, the rooms disappear and they
2267 will be recreated on an available node on first connection attempt.
2268
2269 Available options:
2270 access: AccessName
2271 You can specify who is allowed to use the Multi-User Chat
2272 service. By default everyone is allowed to use it.
2273
2274 access_admin: AccessName
2275 This option specifies who is allowed to administrate the
2276 Multi-User Chat service. The default value is none, which means
2277 that only the room creator can administer their room. The
2278 administrators can send a normal message to the service JID,
2279 and it will be shown in all active rooms as a service message.
2280 The administrators can send a groupchat message to the JID of
2281 an active room, and the message will be shown in the room as a
2282 service message.
2283
2284 access_create: AccessName
2285 To configure who is allowed to create new rooms at the
2286 Multi-User Chat service, this option can be used. By default
2287 any account in the local ejabberd server is allowed to create
2288 rooms.
2289
2290 access_mam: AccessName
2291 To configure who is allowed to modify the mam room option. By
2292 default any account in the local ejabberd server is allowed to
2293 modify that option.
2294
2295 access_persistent: AccessName
2296 To configure who is allowed to modify the persistent room
2297 option. By default any account in the local ejabberd server is
2298 allowed to modify that option.
2299
2300 access_register: AccessName
2301 This option specifies who is allowed to register nickname
2302 within the Multi-User Chat service. The default is all for
2303 backward compatibility, which means that any user is allowed to
2304 register any free nick.
2305
2306 db_type: mnesia | sql
2307 Define the type of persistent storage where the module will
2308 store room information. The default is the storage defined by
2309 the global option default_db, or mnesia if omitted.
2310
2311 default_room_options: Options
2312 This option allows to define the desired default room options.
2313 Note that the creator of a room can modify the options of his
2314 room at any time using an XMPP client with MUC capability. The
2315 Options are:
2316
2317 allow_change_subj: true | false
2318 Allow occupants to change the subject. The default value is
2319 true.
2320
2321 allow_private_messages: true | false
2322 Occupants can send private messages to other occupants. The
2323 default value is true.
2324
2325 allow_private_messages_from_visitors: anyone | moderators |
2326 nobody
2327 Visitors can send private messages to other occupants. The
2328 default value is anyone which means visitors can send
2329 private messages to any occupant.
2330
2331 allow_query_users: true | false
2332 Occupants can send IQ queries to other occupants. The
2333 default value is true.
2334
2335 allow_subscription: true | false
2336 Allow users to subscribe to room events as described in
2337 Multi-User Chat Subscriptions. The default value is false.
2338
2339 allow_user_invites: true | false
2340 Allow occupants to send invitations. The default value is
2341 false.
2342
2343 allow_visitor_nickchange: true | false
2344 Allow visitors to change nickname. The default value is
2345 true.
2346
2347 allow_visitor_status: true | false
2348 Allow visitors to send status text in presence updates. If
2349 disallowed, the status text is stripped before broadcasting
2350 the presence update to all the room occupants. The default
2351 value is true.
2352
2353 anonymous: true | false
2354 The room is anonymous: occupants don’t see the real JIDs of
2355 other occupants. Note that the room moderators can always
2356 see the real JIDs of the occupants. The default value is
2357 true.
2358
2359 captcha_protected: true | false
2360 When a user tries to join a room where they have no
2361 affiliation (not owner, admin or member), the room requires
2362 them to fill a CAPTCHA challenge (see section CAPTCHA in
2363 order to accept their join in the room. The default value
2364 is false.
2365
2366 lang: Language
2367 Preferred language for the discussions in the room. The
2368 language format should conform to RFC 5646. There is no
2369 value by default.
2370
2371 logging: true | false
2372 The public messages are logged using mod_muc_log. The
2373 default value is false.
2374
2375 mam: true | false
2376 Enable message archiving. Implies mod_mam is enabled. The
2377 default value is false.
2378
2379 max_users: Number
2380 Maximum number of occupants in the room. The default value
2381 is 200.
2382
2383 members_by_default: true | false
2384 The occupants that enter the room are participants by
2385 default, so they have "voice". The default value is true.
2386
2387 members_only: true | false
2388 Only members of the room can enter. The default value is
2389 false.
2390
2391 moderated: true | false
2392 Only occupants with "voice" can send public messages. The
2393 default value is true.
2394
2395 password: Password
2396 Password of the room. Implies option password_protected set
2397 to true. There is no default value.
2398
2399 password_protected: true | false
2400 The password is required to enter the room. The default
2401 value is false.
2402
2403 persistent: true | false
2404 The room persists even if the last participant leaves. The
2405 default value is false.
2406
2407 presence_broadcast: [moderator | participant | visitor, ...]
2408 List of roles for which presence is broadcasted. The list
2409 can contain one or several of: moderator, participant,
2410 visitor. The default value is shown in the example below:
2411
2412 Example:
2413
2414 presence_broadcast:
2415 - moderator
2416 - participant
2417 - visitor
2418
2419 public: true | false
2420 The room is public in the list of the MUC service, so it
2421 can be discovered. MUC admins and room participants will
2422 see private rooms in Service Discovery if their XMPP client
2423 supports this feature. The default value is true.
2424
2425 public_list: true | false
2426 The list of participants is public, without requiring to
2427 enter the room. The default value is true.
2428
2429 title: Room Title
2430 A human-readable title of the room. There is no default
2431 value
2432
2433 hibernation_timeout: infinity | Seconds
2434 Timeout before hibernating the room process, expressed in
2435 seconds. The default value is infinity.
2436
2437 history_size: Size
2438 A small history of the current discussion is sent to users when
2439 they enter the room. With this option you can define the number
2440 of history messages to keep and send to users joining the room.
2441 The value is a non-negative integer. Setting the value to 0
2442 disables the history feature and, as a result, nothing is kept
2443 in memory. The default value is 20. This value affects all
2444 rooms on the service. NOTE: modern XMPP clients rely on Message
2445 Archives (XEP-0313), so feel free to disable the history
2446 feature if you’re only using modern clients and have mod_mam
2447 module loaded.
2448
2449 host
2450 Deprecated. Use hosts instead.
2451
2452 hosts: [Host, ...]
2453 This option defines the Jabber IDs of the service. If the hosts
2454 option is not specified, the only Jabber ID will be the
2455 hostname of the virtual host with the prefix "conference.". The
2456 keyword @HOST@ is replaced with the real virtual host name.
2457
2458 max_room_desc: Number
2459 This option defines the maximum number of characters that Room
2460 Description can have when configuring the room. The default
2461 value is infinity.
2462
2463 max_room_id: Number
2464 This option defines the maximum number of characters that Room
2465 ID can have when creating a new room. The default value is
2466 infinity.
2467
2468 max_room_name: Number
2469 This option defines the maximum number of characters that Room
2470 Name can have when configuring the room. The default value is
2471 infinity.
2472
2473 max_rooms_discoitems: Number
2474 When there are more rooms than this Number, only the non-empty
2475 ones are returned in a Service Discovery query. The default
2476 value is 100.
2477
2478 max_user_conferences: Number
2479 This option defines the maximum number of rooms that any given
2480 user can join. The default value is 100. This option is used to
2481 prevent possible abuses. Note that this is a soft limit: some
2482 users can sometimes join more conferences in cluster
2483 configurations.
2484
2485 max_users: Number
2486 This option defines at the service level, the maximum number of
2487 users allowed per room. It can be lowered in each room
2488 configuration but cannot be increased in individual room
2489 configuration. The default value is 200.
2490
2491 max_users_admin_threshold: Number
2492 This option defines the number of service admins or room owners
2493 allowed to enter the room when the maximum number of allowed
2494 occupants was reached. The default limit is 5.
2495
2496 max_users_presence: Number
2497 This option defines after how many users in the room, it is
2498 considered overcrowded. When a MUC room is considered
2499 overcrowed, presence broadcasts are limited to reduce load,
2500 traffic and excessive presence "storm" received by
2501 participants.
2502
2503 min_message_interval: Number
2504 This option defines the minimum interval between two messages
2505 send by an occupant in seconds. This option is global and valid
2506 for all rooms. A decimal value can be used. When this option is
2507 not defined, message rate is not limited. This feature can be
2508 used to protect a MUC service from occupant abuses and limit
2509 number of messages that will be broadcasted by the service. A
2510 good value for this minimum message interval is 0.4 second. If
2511 an occupant tries to send messages faster, an error is send
2512 back explaining that the message has been discarded and
2513 describing the reason why the message is not acceptable.
2514
2515 min_presence_interval: Number
2516 This option defines the minimum of time between presence
2517 changes coming from a given occupant in seconds. This option is
2518 global and valid for all rooms. A decimal value can be used.
2519 When this option is not defined, no restriction is applied.
2520 This option can be used to protect a MUC service for occupants
2521 abuses. If an occupant tries to change its presence more often
2522 than the specified interval, the presence is cached by ejabberd
2523 and only the last presence is broadcasted to all occupants in
2524 the room after expiration of the interval delay. Intermediate
2525 presence packets are silently discarded. A good value for this
2526 option is 4 seconds.
2527
2528 name: string()
2529 The value of the service name. This name is only visible in
2530 some clients that support XEP-0030: Service Discovery. The
2531 default is Chatrooms.
2532
2533 preload_rooms: true | false
2534 Whether to load all persistent rooms in memory on startup. If
2535 disabled, the room is only loaded on first participant join.
2536 The default is true. It makes sense to disable room preloading
2537 when the number of rooms is high: this will improve server
2538 startup time and memory consumption.
2539
2540 queue_type: ram | file
2541 Same as top-level queue_type option, but applied to this module
2542 only.
2543
2544 ram_db_type: mnesia
2545 Define the type of volatile (in-memory) storage where the
2546 module will store room information. The only available value
2547 for this module is mnesia.
2548
2549 regexp_room_id: string()
2550 This option defines the regular expression that a Room ID must
2551 satisfy to allow the room creation. The default value is the
2552 empty string.
2553
2554 room_shaper: none | ShaperName
2555 This option defines shaper for the MUC rooms. The default value
2556 is none.
2557
2558 user_message_shaper: none | ShaperName
2559 This option defines shaper for the users messages. The default
2560 value is none.
2561
2562 user_presence_shaper: none | ShaperName
2563 This option defines shaper for the users presences. The default
2564 value is none.
2565
2566 vcard: vCard
2567 A custom vCard of the service that will be displayed by some
2568 XMPP clients in Service Discovery. The value of vCard is a YAML
2569 map constructed from an XML representation of vCard. Since the
2570 representation has no attributes, the mapping is
2571 straightforward.
2572
2573 For example, the following XML representation of vCard:
2574
2575 <vCard xmlns='vcard-temp'>
2576 <FN>Conferences</FN>
2577 <ADR>
2578 <WORK/>
2579 <STREET>Elm Street</STREET>
2580 </ADR>
2581 </vCard>
2582
2583 will be translated to:
2584
2585 vcard:
2586 fn: Conferences
2587 adr:
2588 -
2589 work: true
2590 street: Elm Street
2591
2592 mod_muc_admin
2593 This module provides commands to administer local MUC services and
2594 their MUC rooms. It also provides simple WebAdmin pages to view the
2595 existing rooms.
2596
2597 This module depends on mod_muc.
2598
2599 The module has no options.
2600
2601 mod_muc_log
2602 This module enables optional logging of Multi-User Chat (MUC) public
2603 conversations to HTML. Once you enable this module, users can join a
2604 room using a MUC capable XMPP client, and if they have enough
2605 privileges, they can request the configuration form in which they can
2606 set the option to enable room logging.
2607
2608 Features:
2609
2610 · Room details are added on top of each page: room title, JID,
2611 author, subject and configuration.
2612
2613 · The room JID in the generated HTML is a link to join the room
2614 (using XMPP URI).
2615
2616 · Subject and room configuration changes are tracked and displayed.
2617
2618 · Joins, leaves, nick changes, kicks, bans and /me are tracked and
2619 displayed, including the reason if available.
2620
2621 · Generated HTML files are XHTML 1.0 Transitional and CSS compliant.
2622
2623 · Timestamps are self-referencing links.
2624
2625 · Links on top for quicker navigation: Previous day, Next day, Up.
2626
2627 · CSS is used for style definition, and a custom CSS file can be
2628 used.
2629
2630 · URLs on messages and subjects are converted to hyperlinks.
2631
2632 · Timezone used on timestamps is shown on the log files.
2633
2634 · A custom link can be added on top of each page.
2635
2636 The module depends on mod_muc.
2637
2638 Available options:
2639 access_log: AccessName
2640 This option restricts which occupants are allowed to enable or
2641 disable room logging. The default value is muc_admin. NOTE: for
2642 this default setting you need to have an access rule for
2643 muc_admin in order to take effect.
2644
2645 cssfile: Path | URL
2646 With this option you can set whether the HTML files should have
2647 a custom CSS file or if they need to use the embedded CSS.
2648 Allowed values are either Path to local file or an URL to a
2649 remote file. By default a predefined CSS will be embedded into
2650 the HTML page.
2651
2652 dirname: room_jid | room_name
2653 Allows to configure the name of the room directory. If set to
2654 room_jid, the room directory name will be the full room JID.
2655 Otherwise, the room directory name will be only the room name,
2656 not including the MUC service name. The default value is
2657 room_jid.
2658
2659 dirtype: subdirs | plain
2660 The type of the created directories can be specified with this
2661 option. If set to subdirs, subdirectories are created for each
2662 year and month. Otherwise, the names of the log files contain
2663 the full date, and there are no subdirectories. The default
2664 value is subdirs.
2665
2666 file_format: html | plaintext
2667 Define the format of the log files: html stores in HTML format,
2668 plaintext stores in plain text. The default value is html.
2669
2670 file_permissions: {mode: Mode, group: Group}
2671 Define the permissions that must be used when creating the log
2672 files: the number of the mode, and the numeric id of the group
2673 that will own the files. The default value is shown in the
2674 example below:
2675
2676 Example:
2677
2678 file_permissions:
2679 mode: 644
2680 group: 33
2681
2682 outdir: Path
2683 This option sets the full path to the directory in which the
2684 HTML files should be stored. Make sure the ejabberd daemon user
2685 has write access on that directory. The default value is
2686 www/muc.
2687
2688 spam_prevention: true | false
2689 If set to true, a special attribute is added to links that
2690 prevent their indexation by search engines. The default value
2691 is true, which mean that nofollow attributes will be added to
2692 user submitted links.
2693
2694 timezone: local | universal
2695 The time zone for the logs is configurable with this option. If
2696 set to local, the local time, as reported to Erlang emulator by
2697 the operating system, will be used. Otherwise, UTC time will be
2698 used. The default value is local.
2699
2700 top_link: {URL: Text}
2701 With this option you can customize the link on the top right
2702 corner of each log file. The default value is shown in the
2703 example below:
2704
2705 Example:
2706
2707 top_link:
2708 /: Home
2709
2710 url: URL
2711 A top level URL where a client can access logs of a particular
2712 conference. The conference name is appended to the URL if
2713 dirname option is set to room_name or a conference JID is
2714 appended to the URL otherwise. There is no default value.
2715
2716 mod_multicast
2717 This module implements a service for XEP-0033: Extended Stanza
2718 Addressing.
2719
2720 Available options:
2721 access: Access
2722 The access rule to restrict who can send packets to the
2723 multicast service. Default value: all.
2724
2725 host
2726 Deprecated. Use hosts instead.
2727
2728 hosts: [Host, ...]
2729 This option defines the Jabber IDs of the service. If the hosts
2730 option is not specified, the only Jabber ID will be the
2731 hostname of the virtual host with the prefix "multicast.". The
2732 keyword @HOST@ is replaced with the real virtual host name. The
2733 default value is multicast.@HOST@.
2734
2735 limits: Sender: Stanza: Number
2736 Specify a list of custom limits which override the default ones
2737 defined in XEP-0033. Limits are defined per sender type and
2738 stanza type, where:
2739
2740 · sender can be: local or remote.
2741
2742 · stanza can be: message or presence.
2743
2744 · number can be a positive integer or infinite.
2745
2746 Example:
2747
2748 # Default values:
2749 local:
2750 message: 100
2751 presence: 100
2752 remote:
2753 message: 20
2754 presence: 20
2755
2756 name
2757 Service name to provide in the Info query to the Service
2758 Discovery. Default is "Multicast".
2759
2760 vcard
2761 vCard element to return when queried. Default value is
2762 undefined.
2763
2764 Example:
2765 # Only admins can send packets to multicast service
2766 access_rules:
2767 multicast:
2768 - allow: admin
2769
2770 # If you want to allow all your users:
2771 access_rules:
2772 multicast:
2773 - allow
2774
2775 # This allows both admins and remote users to send packets,
2776 # but does not allow local users
2777 acl:
2778 allservers:
2779 server_glob: "*"
2780 access_rules:
2781 multicast:
2782 - allow: admin
2783 - deny: local
2784 - allow: allservers
2785
2786 modules:
2787 mod_multicast:
2788 host: multicast.example.org
2789 access: multicast
2790 limits:
2791 local:
2792 message: 40
2793 presence: infinite
2794 remote:
2795 message: 150
2796
2797 mod_offline
2798 This module implements XEP-0160: Best Practices for Handling Offline
2799 Messages and XEP-0013: Flexible Offline Message Retrieval. This means
2800 that all messages sent to an offline user will be stored on the server
2801 until that user comes online again. Thus it is very similar to how
2802 email works. A user is considered offline if no session presence
2803 priority > 0 are currently open.
2804
2805 Note
2806 ejabberdctl has a command to delete expired messages (see chapter
2807 Managing an ejabberd server in online documentation.
2808
2809 Available options:
2810 access_max_user_messages: AccessName
2811 This option defines which access rule will be enforced to limit
2812 the maximum number of offline messages that a user can have
2813 (quota). When a user has too many offline messages, any new
2814 messages that they receive are discarded, and a
2815 <resource-constraint/> error is returned to the sender. The
2816 default value is max_user_offline_messages.
2817
2818 bounce_groupchat: true | false
2819 This option is use the disable an optimisation that avoids
2820 bouncing error messages when groupchat messages could not be
2821 stored as offline. It will reduce chat room load, without any
2822 drawback in standard use cases. You may change default value
2823 only if you have a custom module which uses offline hook after
2824 mod_offline. This option can be useful for both standard MUC
2825 and MucSub, but the bounce is much more likely to happen in the
2826 context of MucSub, so it is even more important to have it on
2827 large MucSub services. The default value is false, meaning the
2828 optimisation is enabled.
2829
2830 cache_life_time: timeout()
2831 Same as top-level cache_life_time option, but applied to this
2832 module only.
2833
2834 cache_size: pos_integer() | infinity
2835 Same as top-level cache_size option, but applied to this module
2836 only.
2837
2838 db_type: mnesia | sql
2839 Same as top-level default_db option, but applied to this module
2840 only.
2841
2842 store_empty_body: true | false | unless_chat_state
2843 Whether or not to store messages that lack a <body/> element.
2844 The default value is unless_chat_state, which tells ejabberd to
2845 store messages even if they lack the <body/> element, unless
2846 they only contain a chat state notification (as defined in
2847 XEP-0085: Chat State Notifications.
2848
2849 store_groupchat: true | false
2850 Whether or not to store groupchat messages. The default value
2851 is false.
2852
2853 use_cache: true | false
2854 Same as top-level use_cache option, but applied to this module
2855 only.
2856
2857 use_mam_for_storage: true | false
2858 This is an experimental option. Enabling this option will make
2859 mod_offline not use the former spool table for storing MucSub
2860 offline messages, but will use the archive table instead. This
2861 use of the archive table is cleaner and it makes it possible
2862 for clients to slowly drop the former offline use case and rely
2863 on message archive instead. It also further reduces the storage
2864 required when you enabled MucSub. Enabling this option has a
2865 known drawback for the moment: most of flexible message
2866 retrieval queries don’t work (those that allow
2867 retrieval/deletion of messages by id), but this specification
2868 is not widely used. The default value is false to keep former
2869 behaviour as default and ensure this option is disabled.
2870
2871 Examples:
2872 This example allows power users to have as much as 5000 offline
2873 messages, administrators up to 2000, and all the other users up to
2874 100:
2875
2876 acl:
2877 admin:
2878 user:
2879 - admin1@localhost
2880 - admin2@example.org
2881 poweruser:
2882 user:
2883 - bob@example.org
2884 - jane@example.org
2885
2886 shaper_rules:
2887 max_user_offline_messages:
2888 - 5000: poweruser
2889 - 2000: admin
2890 - 100
2891
2892 modules:
2893 ...
2894 mod_offline:
2895 access_max_user_messages: max_user_offline_messages
2896 ...
2897
2898 mod_ping
2899 This module implements support for XEP-0199: XMPP Ping and periodic
2900 keepalives. When this module is enabled ejabberd responds correctly to
2901 ping requests, as defined by the protocol.
2902
2903 Available options:
2904 ping_ack_timeout: timeout()
2905 How long to wait before deeming that a client has not answered
2906 a given server ping request. The default value is 32 seconds.
2907
2908 ping_interval: timeout()
2909 How often to send pings to connected clients, if option
2910 send_pings is set to true. If a client connection does not send
2911 or receive any stanza within this interval, a ping request is
2912 sent to the client. The default value is 1 minute.
2913
2914 send_pings: true | false
2915 If this option is set to true, the server sends pings to
2916 connected clients that are not active in a given interval
2917 defined in ping_interval option. This is useful to keep client
2918 connections alive or checking availability. The default value
2919 is false.
2920
2921 timeout_action: none | kill
2922 What to do when a client does not answer to a server ping
2923 request in less than period defined in ping_ack_timeout option:
2924 kill means destroying the underlying connection, none means to
2925 do nothing. NOTE: when mod_stream_mgmt module is loaded and
2926 stream management is enabled by a client, killing the client
2927 connection doesn’t mean killing the client session - the
2928 session will be kept alive in order to give the client a chance
2929 to resume it. The default value is none.
2930
2931 Example:
2932 modules:
2933 ...
2934 mod_ping:
2935 send_pings: true
2936 ping_interval: 4 min
2937 timeout_action: kill
2938 ...
2939
2940 mod_pres_counter
2941 This module detects flood/spam in presence subscriptions traffic. If a
2942 user sends or receives more of those stanzas in a given time interval,
2943 the exceeding stanzas are silently dropped, and a warning is logged.
2944
2945 Available options:
2946 count: Number
2947 The number of subscription presence stanzas (subscribe,
2948 unsubscribe, subscribed, unsubscribed) allowed for any
2949 direction (input or output) per time defined in interval
2950 option. Please note that two users subscribing to each other
2951 usually generate 4 stanzas, so the recommended value is 4 or
2952 more. The default value is 5.
2953
2954 interval: timeout()
2955 The time interval. The default value is 1 minute.
2956
2957 Example:
2958 modules:
2959 ...
2960 mod_pres_counter:
2961 count: 5
2962 interval: 30 secs
2963 ...
2964
2965 mod_privacy
2966 This module implements XEP-0016: Privacy Lists.
2967
2968 Note
2969 Nowadays modern XMPP clients rely on XEP-0191: Blocking Command
2970 which is implemented by mod_blocking module. However, you still
2971 need mod_privacy loaded in order for mod_blocking to work.
2972
2973 Available options:
2974 cache_life_time: timeout()
2975 Same as top-level cache_life_time option, but applied to this
2976 module only.
2977
2978 cache_missed: true | false
2979 Same as top-level cache_missed option, but applied to this
2980 module only.
2981
2982 cache_size: pos_integer() | infinity
2983 Same as top-level cache_size option, but applied to this module
2984 only.
2985
2986 db_type: mnesia | sql
2987 Same as top-level default_db option, but applied to this module
2988 only.
2989
2990 use_cache: true | false
2991 Same as top-level use_cache option, but applied to this module
2992 only.
2993
2994 mod_private
2995 This module adds support for XEP-0049: Private XML Storage.
2996
2997 Using this method, XMPP entities can store private data on the server,
2998 retrieve it whenever necessary and share it between multiple connected
2999 clients of the same user. The data stored might be anything, as long as
3000 it is a valid XML. One typical usage is storing a bookmark of all
3001 user’s conferences (XEP-0048: Bookmarks).
3002
3003 Available options:
3004 cache_life_time: timeout()
3005 Same as top-level cache_life_time option, but applied to this
3006 module only.
3007
3008 cache_missed: true | false
3009 Same as top-level cache_missed option, but applied to this
3010 module only.
3011
3012 cache_size: pos_integer() | infinity
3013 Same as top-level cache_size option, but applied to this module
3014 only.
3015
3016 db_type: mnesia | sql
3017 Same as top-level default_db option, but applied to this module
3018 only.
3019
3020 use_cache: true | false
3021 Same as top-level use_cache option, but applied to this module
3022 only.
3023
3024 mod_privilege
3025 This module is an implementation of XEP-0356: Privileged Entity. This
3026 extension allows components to have privileged access to other entity
3027 data (send messages on behalf of the server or on behalf of a user,
3028 get/set user roster, access presence information, etc.). This may be
3029 used to write powerful external components, for example implementing an
3030 external PEP or MAM service.
3031
3032 By default a component does not have any privileged access. It is worth
3033 noting that the permissions grant access to the component to a specific
3034 data type for all users of the virtual host on which mod_privilege is
3035 loaded.
3036
3037 Make sure you have a listener configured to connect your component.
3038 Check the section about listening ports for more information.
3039
3040 Warning
3041 Security issue: Privileged access gives components access to
3042 sensitive data, so permission should be granted carefully, only if
3043 you trust a component.
3044
3045 Note
3046 This module is complementary to mod_delegation, but can also be
3047 used separately.
3048
3049 Available options:
3050 message: Options
3051 This option defines permissions for messages. By default no
3052 permissions are given. The Options are:
3053
3054 outgoing: AccessName
3055 The option defines an access rule for sending outgoing
3056 messages by the component. The default value is none.
3057
3058 presence: Options
3059 This option defines permissions for presences. By default no
3060 permissions are given. The Options are:
3061
3062 managed_entity: AccessName
3063 An access rule that gives permissions to the component to
3064 receive server presences. The default value is none.
3065
3066 roster: AccessName
3067 An access rule that gives permissions to the component to
3068 receive the presence of both the users and the contacts in
3069 their roster. The default value is none.
3070
3071 roster: Options
3072 This option defines roster permissions. By default no
3073 permissions are given. The Options are:
3074
3075 both: AccessName
3076 Sets read/write access to a user’s roster. The default
3077 value is none.
3078
3079 get: AccessName
3080 Sets read access to a user’s roster. The default value is
3081 none.
3082
3083 set: AccessName
3084 Sets write access to a user’s roster. The default value is
3085 none.
3086
3087 Example:
3088 modules:
3089 ...
3090 mod_privilege:
3091 roster:
3092 get: all
3093 presence:
3094 managed_entity: all
3095 message:
3096 outgoing: all
3097 ...
3098
3099 mod_proxy65
3100 This module implements XEP-0065: SOCKS5 Bytestreams. It allows ejabberd
3101 to act as a file transfer proxy between two XMPP clients.
3102
3103 Available options:
3104 access: AccessName
3105 Defines an access rule for file transfer initiators. The
3106 default value is all. You may want to restrict access to the
3107 users of your server only, in order to avoid abusing your proxy
3108 by the users of remote servers.
3109
3110 auth_type: anonymous | plain
3111 SOCKS5 authentication type. The default value is anonymous. If
3112 set to plain, ejabberd will use authentication backend as it
3113 would for SASL PLAIN.
3114
3115 host
3116 Deprecated. Use hosts instead.
3117
3118 hostname: Host
3119 Defines a hostname offered by the proxy when establishing a
3120 session with clients. This is useful when you run the proxy
3121 behind a NAT. The keyword @HOST@ is replaced with the virtual
3122 host name. The default is to use the value of ip option.
3123 Examples: proxy.mydomain.org, 200.150.100.50.
3124
3125 hosts: [Host, ...]
3126 This option defines the Jabber IDs of the service. If the hosts
3127 option is not specified, the only Jabber ID will be the
3128 hostname of the virtual host with the prefix "proxy.". The
3129 keyword @HOST@ is replaced with the real virtual host name.
3130
3131 ip: IPAddress
3132 This option specifies which network interface to listen for.
3133 The default value is an IP address of the service’s DNS name,
3134 or, if fails, 127.0.0.1.
3135
3136 max_connections: pos_integer() | infinity
3137 Maximum number of active connections per file transfer
3138 initiator. The default value is infinity.
3139
3140 name: Name
3141 The value of the service name. This name is only visible in
3142 some clients that support XEP-0030: Service Discovery. The
3143 default is "SOCKS5 Bytestreams".
3144
3145 port: 1..65535
3146 A port number to listen for incoming connections. The default
3147 value is 7777.
3148
3149 ram_db_type: mnesia | redis | sql
3150 Define the type of volatile (in-memory) storage where the
3151 module will store room information.
3152
3153 recbuf: Size
3154 A size of the buffer for incoming packets. If you define a
3155 shaper, set the value of this option to the size of the shaper
3156 in order to avoid traffic spikes in file transfers. The default
3157 value is 65536 bytes.
3158
3159 shaper: Shaper
3160 This option defines a shaper for the file transfer peers. A
3161 shaper with the maximum bandwidth will be selected. The default
3162 is none, i.e. no shaper.
3163
3164 sndbuf: Size
3165 A size of the buffer for outgoing packets. If you define a
3166 shaper, set the value of this option to the size of the shaper
3167 in order to avoid traffic spikes in file transfers. The default
3168 value is 65536 bytes.
3169
3170 vcard: vCard
3171 A custom vCard of the service that will be displayed by some
3172 XMPP clients in Service Discovery. The value of vCard is a YAML
3173 map constructed from an XML representation of vCard. Since the
3174 representation has no attributes, the mapping is
3175 straightforward.
3176
3177 For example, the following XML representation of vCard:
3178
3179 <vCard xmlns='vcard-temp'>
3180 <FN>Conferences</FN>
3181 <ADR>
3182 <WORK/>
3183 <STREET>Elm Street</STREET>
3184 </ADR>
3185 </vCard>
3186
3187 will be translated to:
3188
3189 vcard:
3190 fn: Conferences
3191 adr:
3192 -
3193 work: true
3194 street: Elm Street
3195
3196 Example:
3197 acl:
3198 admin:
3199 user: admin@example.org
3200 proxy_users:
3201 server: example.org
3202
3203 access_rules:
3204 proxy65_access:
3205 allow: proxy_users
3206
3207 shaper_rules:
3208 proxy65_shaper:
3209 none: admin
3210 proxyrate: proxy_users
3211
3212 shaper:
3213 proxyrate: 10240
3214
3215 modules:
3216 ...
3217 mod_proxy65:
3218 host: proxy1.example.org
3219 name: "File Transfer Proxy"
3220 ip: 200.150.100.1
3221 port: 7778
3222 max_connections: 5
3223 access: proxy65_access
3224 shaper: proxy65_shaper
3225 recbuf: 10240
3226 sndbuf: 10240
3227 ...
3228
3229 mod_pubsub
3230 This module offers a service for XEP-0060: Publish-Subscribe. The
3231 functionality in mod_pubsub can be extended using plugins. The plugin
3232 that implements PEP (XEP-0163: Personal Eventing via Pubsub) is enabled
3233 in the default ejabberd configuration file, and it requires mod_caps.
3234
3235 Available options:
3236 access_createnode: AccessName
3237 This option restricts which users are allowed to create pubsub
3238 nodes using acl and access. By default any account in the local
3239 ejabberd server is allowed to create pubsub nodes. The default
3240 value is: all.
3241
3242 db_type: mnesia | sql
3243 Same as top-level default_db option, but applied to this module
3244 only.
3245
3246 default_node_config: List of Key:Value
3247 To override default node configuration, regardless of node
3248 plugin. Value is a list of key-value definition. Node
3249 configuration still uses default configuration defined by node
3250 plugin, and overrides any items by value defined in this
3251 configurable list.
3252
3253 force_node_config: List of Node and the list of its Key:Value
3254 Define the configuration for given nodes. The default value is:
3255 [].
3256
3257 Example:
3258
3259 force_node_config:
3260 ## Avoid buggy clients to make their bookmarks public
3261 storage:bookmarks:
3262 access_model: whitelist
3263
3264 host
3265 Deprecated. Use hosts instead.
3266
3267 hosts: [Host, ...]
3268 This option defines the Jabber IDs of the service. If the hosts
3269 option is not specified, the only Jabber ID will be the
3270 hostname of the virtual host with the prefix "vjud.". The
3271 keyword @HOST@ is replaced with the real virtual host name.
3272
3273 ignore_pep_from_offline: false | true
3274 To specify whether or not we should get last published PEP
3275 items from users in our roster which are offline when we
3276 connect. Value is true or false. If not defined, pubsub assumes
3277 true so we only get last items of online contacts.
3278
3279 last_item_cache: false | true
3280 To specify whether or not pubsub should cache last items. Value
3281 is true or false. If not defined, pubsub does not cache last
3282 items. On systems with not so many nodes, caching last items
3283 speeds up pubsub and allows to raise user connection rate. The
3284 cost is memory usage, as every item is stored in memory.
3285
3286 max_items_node: MaxItems
3287 Define the maximum number of items that can be stored in a
3288 node. Default value is: 10.
3289
3290 max_nodes_discoitems: pos_integer() | infinity
3291 The maximum number of nodes to return in a discoitem response.
3292 The default value is: 100.
3293
3294 max_subscriptions_node: MaxSubs
3295 Define the maximum number of subscriptions managed by a node.
3296 Default value is no limitation: undefined.
3297
3298 name: Name
3299 The value of the service name. This name is only visible in
3300 some clients that support XEP-0030: Service Discovery. The
3301 default is vCard User Search.
3302
3303 nodetree: Nodetree
3304 To specify which nodetree to use. If not defined, the default
3305 pubsub nodetree is used: tree. Only one nodetree can be used
3306 per host, and is shared by all node plugins.
3307
3308 · tree nodetree store node configuration and relations on the
3309 database. flat nodes are stored without any relationship,
3310 and hometree nodes can have child nodes.
3311
3312 · virtual nodetree does not store nodes on database. This
3313 saves resources on systems with tons of nodes. If using the
3314 virtual nodetree, you can only enable those node plugins:
3315 [flat, pep] or [flat]; any other plugins configuration will
3316 not work. Also, all nodes will have the default
3317 configuration, and this can not be changed. Using virtual
3318 nodetree requires to start from a clean database, it will
3319 not work if you used the default tree nodetree before.
3320
3321 · dag nodetree provides experimental support for PubSub
3322 Collection Nodes (XEP-0248). In that case you should also
3323 add dag node plugin as default, for example: plugins:
3324 [flat,pep]
3325
3326 pep_mapping: List of Key:Value
3327 This allows to define a list of key-value to choose defined
3328 node plugins on given PEP namespace. The following example will
3329 use node_tune instead of node_pep for every PEP node with the
3330 tune namespace:
3331
3332 Example:
3333
3334 modules:
3335 ...
3336 mod_pubsub:
3337 pep_mapping:
3338 http://jabber.org/protocol/tune: tune
3339 ...
3340
3341 plugins: [Plugin, ...]
3342 To specify which pubsub node plugins to use. The first one in
3343 the list is used by default. If this option is not defined, the
3344 default plugins list is: [flat]. PubSub clients can define
3345 which plugin to use when creating a node: add
3346 type='plugin-name' attribute to the create stanza element.
3347
3348 · flat plugin handles the default behaviour and follows
3349 standard XEP-0060 implementation.
3350
3351 · pep plugin adds extention to handle Personal Eventing
3352 Protocol (XEP-0163) to the PubSub engine. Adding pep allows
3353 to handle PEP automatically.
3354
3355 vcard: vCard
3356 A custom vCard of the server that will be displayed by some
3357 XMPP clients in Service Discovery. The value of vCard is a YAML
3358 map constructed from an XML representation of vCard. Since the
3359 representation has no attributes, the mapping is
3360 straightforward.
3361
3362 The following XML representation of vCard:
3363
3364 <vCard xmlns='vcard-temp'>
3365 <FN>PubSub Service</FN>
3366 <ADR>
3367 <WORK/>
3368 <STREET>Elm Street</STREET>
3369 </ADR>
3370 </vCard>
3371
3372 will be translated to:
3373
3374 vcard:
3375 fn: PubSub Service
3376 adr:
3377 -
3378 work: true
3379 street: Elm Street
3380
3381 Examples:
3382 Example of configuration that uses flat nodes as default, and
3383 allows use of flat, hometree and pep nodes:
3384
3385 modules:
3386 ...
3387 mod_pubsub:
3388 access_createnode: pubsub_createnode
3389 max_subscriptions_node: 100
3390 default_node_config:
3391 notification_type: normal
3392 notify_retract: false
3393 max_items: 4
3394 plugins:
3395 - flat
3396 - pep
3397 ...
3398
3399 Using relational database requires using mod_pubsub with db_type
3400 sql. Only flat, hometree and pep plugins supports SQL. The
3401 following example shows previous configuration with SQL usage:
3402
3403 modules:
3404 ...
3405 mod_pubsub:
3406 db_type: sql
3407 access_createnode: pubsub_createnode
3408 ignore_pep_from_offline: true
3409 last_item_cache: false
3410 plugins:
3411 - flat
3412 - pep
3413 ...
3414
3415 mod_push
3416 This module implements the XMPP server’s part of the push notification
3417 solution specified in XEP-0357: Push Notifications. It does not
3418 generate, for example, APNS or FCM notifications directly. Instead,
3419 it’s designed to work with so-called "app servers" operated by
3420 third-party vendors of mobile apps. Those app servers will usually
3421 trigger notification delivery to the user’s mobile device using
3422 platform-dependant backend services such as FCM or APNS.
3423
3424 Available options:
3425 cache_life_time: timeout()
3426 Same as top-level cache_life_time option, but applied to this
3427 module only.
3428
3429 cache_missed: true | false
3430 Same as top-level cache_missed option, but applied to this
3431 module only.
3432
3433 cache_size: pos_integer() | infinity
3434 Same as top-level cache_size option, but applied to this module
3435 only.
3436
3437 db_type: mnesia | sql
3438 Same as top-level default_db option, but applied to this module
3439 only.
3440
3441 include_body: true | false | Text
3442 If this option is set to true, the message text is included
3443 with push notifications generated for incoming messages with a
3444 body. The option can instead be set to a static Text, in which
3445 case the specified text will be included in place of the actual
3446 message body. This can be useful to signal the app server
3447 whether the notification was triggered by a message with body
3448 (as opposed to other types of traffic) without leaking actual
3449 message contents. The default value is "New message".
3450
3451 include_sender: true | false
3452 If this option is set to true, the sender’s JID is included
3453 with push notifications generated for incoming messages with a
3454 body. The default value is false.
3455
3456 use_cache: true | false
3457 Same as top-level use_cache option, but applied to this module
3458 only.
3459
3460 mod_push_keepalive
3461 This module tries to keep the stream management session (see
3462 mod_stream_mgmt) of a disconnected mobile client alive if the client
3463 enabled push notifications for that session. However, the normal
3464 session resumption timeout is restored once a push notification is
3465 issued, so the session will be closed if the client doesn’t respond to
3466 push notifications.
3467
3468 The module depends on mod_push.
3469
3470 Available options:
3471 resume_timeout: timeout()
3472 This option specifies the period of time until the session of a
3473 disconnected push client times out. This timeout is only in
3474 effect as long as no push notification is issued. Once that
3475 happened, the resumption timeout configured for the
3476 mod_stream_mgmt module is restored. The default value is 72
3477 minutes.
3478
3479 wake_on_start: true | false
3480 If this option is set to true, notifications are generated for
3481 all registered push clients during server startup. This option
3482 should not be enabled on servers with many push clients as it
3483 can generate significant load on the involved push services and
3484 the server itself. The default value is false.
3485
3486 wake_on_timeout: true | false
3487 If this option is set to true, a notification is generated
3488 shortly before the session would time out as per the
3489 resume_timeout option. The default value is true.
3490
3491 mod_register
3492 This module adds support for XEP-0077: In-Band Registration. This
3493 protocol enables end users to use a XMPP client to:
3494
3495 · Register a new account on the server.
3496
3497 · Change the password from an existing account on the server.
3498
3499 · Delete an existing account on the server.
3500
3501 This module reads also another option defined globally for the server:
3502 registration_timeout. Please check that option documentation in the
3503 section with top-level options.
3504
3505 Available options:
3506 access: AccessName
3507 Specify rules to restrict what usernames can be registered and
3508 unregistered. If a rule returns deny on the requested username,
3509 registration and unregistration of that user name is denied.
3510 There are no restrictions by default.
3511
3512 access_from: AccessName
3513 By default, ejabberd doesn’t allow to register new accounts
3514 from s2s or existing c2s sessions. You can change it by
3515 defining access rule in this option. Use with care: allowing
3516 registration from s2s leads to uncontrolled massive accounts
3517 creation by rogue users.
3518
3519 access_remove: AccessName
3520 Specify rules to restrict access for user unregistration. By
3521 default any user is able to unregister their account.
3522
3523 captcha_protected: true | false
3524 Protect registrations with CAPTCHA (see section CAPTCHA of the
3525 Configuration Guide). The default is false.
3526
3527 ip_access: AccessName
3528 Define rules to allow or deny account registration depending on
3529 the IP address of the XMPP client. The AccessName should be of
3530 type ip. The default value is all.
3531
3532 password_strength: Entropy
3533 This option sets the minimum Shannon entropy for passwords. The
3534 value Entropy is a number of bits of entropy. The recommended
3535 minimum is 32 bits. The default is 0, i.e. no checks are
3536 performed.
3537
3538 redirect_url: URL
3539 This option enables registration redirection as described in
3540 XEP-0077: In-Band Registration: Redirection.
3541
3542 registration_watchers: [JID, ...]
3543 This option defines a list of JIDs which will be notified each
3544 time a new account is registered.
3545
3546 welcome_message: {subject: Subject, body: Body}
3547 Set a welcome message that is sent to each newly registered
3548 account. The message will have subject Subject and text Body.
3549
3550 mod_register_web
3551 This module provides a web page where users can:
3552
3553 · Register a new account on the server.
3554
3555 · Change the password from an existing account on the server.
3556
3557 · Delete an existing account on the server.
3558
3559 This module supports CAPTCHA image to register a new account. To enable
3560 this feature, configure the options captcha_cmd and captcha_url, which
3561 are documented in the section with top-level options.
3562
3563 As an example usage, the users of the host example.org can visit the
3564 page: https://example.org:5281/register/ It is important to include the
3565 last / character in the URL, otherwise the subpages URL will be
3566 incorrect.
3567
3568 The module depends on mod_register where all the configuration is
3569 performed.
3570
3571 The module has no options.
3572
3573 mod_roster
3574 This module implements roster management as defined in RFC6121 Section
3575 2. The module also adds support for XEP-0237: Roster Versioning.
3576
3577 Available options:
3578 access: AccessName
3579 This option can be configured to specify rules to restrict
3580 roster management. If the rule returns deny on the requested
3581 user name, that user cannot modify their personal roster, i.e.
3582 they cannot add/remove/modify contacts or send presence
3583 subscriptions. The default value is all, i.e. no restrictions.
3584
3585 cache_life_time: timeout()
3586 Same as top-level cache_life_time option, but applied to this
3587 module only.
3588
3589 cache_missed: true | false
3590 Same as top-level cache_missed option, but applied to this
3591 module only.
3592
3593 cache_size: pos_integer() | infinity
3594 Same as top-level cache_size option, but applied to this module
3595 only.
3596
3597 db_type: mnesia | sql
3598 Same as top-level default_db option, but applied to this module
3599 only.
3600
3601 store_current_id: true | false
3602 If this option is set to true, the current roster version
3603 number is stored on the database. If set to false, the roster
3604 version number is calculated on the fly each time. Enabling
3605 this option reduces the load for both ejabberd and the
3606 database. This option does not affect the client in any way.
3607 This option is only useful if option versioning is set to true.
3608 The default value is false. IMPORTANT: if you use
3609 mod_shared_roster or mod_shared_roster_ldap, you must set the
3610 value of the option to false.
3611
3612 use_cache: true | false
3613 Same as top-level use_cache option, but applied to this module
3614 only.
3615
3616 versioning: true | false
3617 Enables/disables Roster Versioning. The default value is false.
3618
3619 Example:
3620 modules:
3621 ...
3622 mod_roster:
3623 versioning: true
3624 store_current_id: false
3625 ...
3626
3627 mod_s2s_dialback
3628 The module adds support for XEP-0220: Server Dialback to provide server
3629 identity verification based on DNS.
3630
3631 Warning
3632 DNS-based verification is vulnerable to DNS cache poisoning, so
3633 modern servers rely on verification based on PKIX certificates.
3634 Thus this module is only recommended for backward compatibility
3635 with servers running outdated software or non-TLS servers, or those
3636 with invalid certificates (as long as you accept the risks, e.g.
3637 you assume that the remote server has an invalid certificate due to
3638 poor administration and not because it’s compromised).
3639
3640 Available options:
3641 access: AccessName
3642 An access rule that can be used to restrict dialback for some
3643 servers. The default value is all.
3644
3645 Example:
3646 modules:
3647 ...
3648 mod_s2s_dialback:
3649 access:
3650 allow:
3651 server: legacy.domain.tld
3652 server: invalid-cert.example.org
3653 deny: all
3654 ...
3655
3656 mod_service_log
3657 This module forwards copies of all stanzas to remote XMPP servers or
3658 components. Every stanza is encapsulated into <forwarded/> element as
3659 described in XEP-0297: Stanza Forwarding.
3660
3661 Available options:
3662 loggers: [Domain, ...]
3663 A list of servers or connected components to which stanzas will
3664 be forwarded.
3665
3666 Example:
3667 modules:
3668 ...
3669 mod_service_log:
3670 loggers:
3671 - xmpp-server.tld
3672 - component.domain.tld
3673 ...
3674
3675 mod_shared_roster
3676 This module enables you to create shared roster groups: groups of
3677 accounts that can see members from (other) groups in their rosters.
3678
3679 The big advantages of this feature are that end users do not need to
3680 manually add all users to their rosters, and that they cannot
3681 permanently delete users from the shared roster groups. A shared roster
3682 group can have members from any XMPP server, but the presence will only
3683 be available from and to members of the same virtual host where the
3684 group is created. It still allows the users to have / add their own
3685 contacts, as it does not replace the standard roster. Instead, the
3686 shared roster contacts are merged to the relevant users at retrieval
3687 time. The standard user rosters thus stay unmodified.
3688
3689 Shared roster groups can be edited via the Web Admin, and some API
3690 commands called srg_*. Each group has a unique name and those
3691 parameters:
3692
3693 · Label: Used in the rosters where this group is displayed.
3694
3695 · Description: of the group, which has no effect.
3696
3697 · Members: A list of JIDs of group members, entered one per line in
3698 the Web Admin. The special member directive @all@ represents all
3699 the registered users in the virtual host; which is only recommended
3700 for a small server with just a few hundred users. The special
3701 member directive @online@ represents the online users in the
3702 virtual host. With those two directives, the actual list of members
3703 in those shared rosters is generated dynamically at retrieval time.
3704
3705 · Displayed: A list of groups that will be in the rosters of this
3706 group’s members. A group of other vhost can be identified with
3707 groupid@vhost.
3708
3709 This module depends on mod_roster. If not enabled, roster queries will
3710 return 503 errors.
3711
3712 Available options:
3713 cache_life_time: timeout()
3714 Same as top-level cache_life_time option, but applied to this
3715 module only.
3716
3717 cache_missed: true | false
3718 Same as top-level cache_missed option, but applied to this
3719 module only.
3720
3721 cache_size: pos_integer() | infinity
3722 Same as top-level cache_size option, but applied to this module
3723 only.
3724
3725 db_type: mnesia | sql
3726 Define the type of storage where the module will create the
3727 tables and store user information. The default is the storage
3728 defined by the global option default_db, or mnesia if omitted.
3729 If sql value is defined, make sure you have defined the
3730 database.
3731
3732 use_cache: true | false
3733 Same as top-level use_cache option, but applied to this module
3734 only.
3735
3736 Examples:
3737 Take the case of a computer club that wants all its members seeing
3738 each other in their rosters. To achieve this, they need to create a
3739 shared roster group similar to this one:
3740
3741 Name: club_members
3742 Label: Club Members
3743 Description: Members from the computer club
3744 Members: member1@example.org, member2@example.org, member3@example.org
3745 Displayed Groups: club_members
3746
3747 In another case we have a company which has three divisions:
3748 Management, Marketing and Sales. All group members should see all
3749 other members in their rosters. Additionally, all managers should
3750 have all marketing and sales people in their roster.
3751 Simultaneously, all marketeers and the whole sales team should see
3752 all managers. This scenario can be achieved by creating shared
3753 roster groups as shown in the following lists:
3754
3755 First list:
3756 Name: management
3757 Label: Management
3758 Description: Management
3759 Members: manager1@example.org, manager2@example.org
3760 Displayed: management, marketing, sales
3761
3762 Second list:
3763 Name: marketing
3764 Label: Marketing
3765 Description: Marketing
3766 Members: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org
3767 Displayed: management, marketing
3768
3769 Third list:
3770 Name: sales
3771 Label: Sales
3772 Description: Sales
3773 Members: salesman1@example.org, salesman2@example.org, salesman3@example.org
3774 Displayed: management, sales
3775
3776 mod_shared_roster_ldap
3777 This module lets the server administrator automatically populate users'
3778 rosters (contact lists) with entries based on users and groups defined
3779 in an LDAP-based directory.
3780
3781 Note
3782 mod_shared_roster_ldap depends on mod_roster being enabled. Roster
3783 queries will return 503 errors if mod_roster is not enabled.
3784
3785 The module accepts many configuration options. Some of them, if
3786 unspecified, default to the values specified for the top level of
3787 configuration. This lets you avoid specifying, for example, the bind
3788 password in multiple places.
3789
3790 · Filters: ldap_rfilter, ldap_ufilter, ldap_gfilter, ldap_filter.
3791 These options specify LDAP filters used to query for shared roster
3792 information. All of them are run against the ldap_base.
3793
3794 · Attributes: ldap_groupattr, ldap_groupdesc, ldap_memberattr,
3795 ldap_userdesc, ldap_useruid. These options specify the names of the
3796 attributes which hold interesting data in the entries returned by
3797 running filters specified with the filter options.
3798
3799 · Control parameters: ldap_auth_check, ldap_group_cache_validity,
3800 ldap_memberattr_format, ldap_memberattr_format_re,
3801 ldap_user_cache_validity. These parameters control the behaviour of
3802 the module.
3803
3804 · Connection parameters: The module also accepts the connection
3805 parameters, all of which default to the top-level parameter of the
3806 same name, if unspecified. See LDAP Connection section for more
3807 information about them.
3808
3809 Check also the Configuration examples section to get details about
3810 retrieving the roster, and configuration examples including Flat DIT
3811 and Deep DIT.
3812
3813 Available options:
3814 cache_life_time
3815 Same as top-level cache_life_time option, but applied to this
3816 module only.
3817
3818 cache_missed
3819 Same as top-level cache_missed option, but applied to this
3820 module only.
3821
3822 cache_size
3823 Same as top-level cache_size option, but applied to this module
3824 only.
3825
3826 ldap_auth_check: true | false
3827 Whether the module should check (via the ejabberd
3828 authentication subsystem) for existence of each user in the
3829 shared LDAP roster. Set to false if you want to disable the
3830 check. Default value is true.
3831
3832 ldap_backups
3833 Same as top-level ldap_backups option, but applied to this
3834 module only.
3835
3836 ldap_base
3837 Same as top-level ldap_base option, but applied to this module
3838 only.
3839
3840 ldap_deref_aliases
3841 Same as top-level ldap_deref_aliases option, but applied to
3842 this module only.
3843
3844 ldap_encrypt
3845 Same as top-level ldap_encrypt option, but applied to this
3846 module only.
3847
3848 ldap_filter
3849 Additional filter which is AND-ed together with "User Filter"
3850 and "Group Filter". For more information check the LDAP Filters
3851 section.
3852
3853 ldap_gfilter
3854 "Group Filter", used when retrieving human-readable name
3855 (a.k.a. "Display Name") and the members of a group. See also
3856 the parameters ldap_groupattr, ldap_groupdesc and
3857 ldap_memberattr. If unspecified, defaults to the top-level
3858 parameter of the same name. If that one also is unspecified,
3859 then the filter is constructed exactly like "User Filter".
3860
3861 ldap_groupattr
3862 The name of the attribute that holds the group name, and that
3863 is used to differentiate between them. Retrieved from results
3864 of the "Roster Filter" and "Group Filter". Defaults to cn.
3865
3866 ldap_groupdesc
3867 The name of the attribute which holds the human-readable group
3868 name in the objects you use to represent groups. Retrieved from
3869 results of the "Group Filter". Defaults to whatever
3870 ldap_groupattr is set.
3871
3872 ldap_memberattr
3873 The name of the attribute which holds the IDs of the members of
3874 a group. Retrieved from results of the "Group Filter". Defaults
3875 to memberUid. The name of the attribute differs depending on
3876 the objectClass you use for your group objects, for example:
3877 posixGroup → memberUid; groupOfNames → member;
3878 groupOfUniqueNames → uniqueMember.
3879
3880 ldap_memberattr_format
3881 A globbing format for extracting user ID from the value of the
3882 attribute named by ldap_memberattr. Defaults to %u, which means
3883 that the whole value is the member ID. If you change it to
3884 something different, you may also need to specify the User and
3885 Group Filters manually; see section Filters.
3886
3887 ldap_memberattr_format_re
3888 A regex for extracting user ID from the value of the attribute
3889 named by ldap_memberattr. Check the LDAP Control Parameters
3890 section.
3891
3892 ldap_password
3893 Same as top-level ldap_password option, but applied to this
3894 module only.
3895
3896 ldap_port
3897 Same as top-level ldap_port option, but applied to this module
3898 only.
3899
3900 ldap_rfilter
3901 So called "Roster Filter". Used to find names of all "shared
3902 roster" groups. See also the ldap_groupattr parameter. If
3903 unspecified, defaults to the top-level parameter of the same
3904 name. You must specify it in some place in the configuration,
3905 there is no default.
3906
3907 ldap_rootdn
3908 Same as top-level ldap_rootdn option, but applied to this
3909 module only.
3910
3911 ldap_servers
3912 Same as top-level ldap_servers option, but applied to this
3913 module only.
3914
3915 ldap_tls_cacertfile
3916 Same as top-level ldap_tls_cacertfile option, but applied to
3917 this module only.
3918
3919 ldap_tls_certfile
3920 Same as top-level ldap_tls_certfile option, but applied to this
3921 module only.
3922
3923 ldap_tls_depth
3924 Same as top-level ldap_tls_depth option, but applied to this
3925 module only.
3926
3927 ldap_tls_verify
3928 Same as top-level ldap_tls_verify option, but applied to this
3929 module only.
3930
3931 ldap_ufilter
3932 "User Filter", used for retrieving the human-readable name of
3933 roster entries (usually full names of people in the roster).
3934 See also the parameters ldap_userdesc and ldap_useruid. For
3935 more information check the LDAP Filters section.
3936
3937 ldap_uids
3938 Same as top-level ldap_uids option, but applied to this module
3939 only.
3940
3941 ldap_userdesc
3942 The name of the attribute which holds the human-readable user
3943 name. Retrieved from results of the "User Filter". Defaults to
3944 cn.
3945
3946 ldap_useruid
3947 The name of the attribute which holds the ID of a roster item.
3948 Value of this attribute in the roster item objects needs to
3949 match the ID retrieved from the ldap_memberattr attribute of a
3950 group object. Retrieved from results of the "User Filter".
3951 Defaults to cn.
3952
3953 use_cache
3954 Same as top-level use_cache option, but applied to this module
3955 only.
3956
3957 mod_sic
3958 This module adds support for XEP-0279: Server IP Check. This protocol
3959 enables a client to discover its external IP address.
3960
3961 Warning
3962 The protocol extension is deferred and seems like there are no
3963 clients supporting it, so using this module is not recommended and,
3964 furthermore, the module might be removed in the future.
3965
3966 The module has no options.
3967
3968 mod_sip
3969 This module adds SIP proxy/registrar support for the corresponding
3970 virtual host.
3971
3972 Note
3973 It is not enough to just load this module. You should also
3974 configure listeners and DNS records properly. For details see the
3975 section about the ejabberd_sip listen module in the ejabberd
3976 Documentation.
3977
3978 Available options:
3979 always_record_route: true | false
3980 Always insert "Record-Route" header into SIP messages. This
3981 approach allows to bypass NATs/firewalls a bit more easily. The
3982 default value is true.
3983
3984 flow_timeout_tcp: timeout()
3985 The option sets a keep-alive timer for SIP outbound TCP
3986 connections. The default value is 2 minutes.
3987
3988 flow_timeout_udp: timeout()
3989 The options sets a keep-alive timer for SIP outbound UDP
3990 connections. The default value is 29 seconds.
3991
3992 record_route: URI
3993 When the option always_record_route is set to true or when SIP
3994 outbound is utilized, ejabberd inserts "Record-Route" header
3995 field with this URI into a SIP message. The default is a SIP
3996 URI constructed from the virtual host on which the module is
3997 loaded.
3998
3999 routes: [URI, ...]
4000 You can set a list of SIP URIs of routes pointing to this SIP
4001 proxy server. The default is a list containing a single SIP URI
4002 constructed from the virtual host on which the module is
4003 loaded.
4004
4005 via: [URI, ...]
4006 A list to construct "Via" headers for inserting them into
4007 outgoing SIP messages. This is useful if you’re running your
4008 SIP proxy in a non-standard network topology. Every URI element
4009 in the list must be in the form of "scheme://host:port", where
4010 "transport" must be tls, tcp, or udp, "host" must be a domain
4011 name or an IP address and "port" must be an internet port
4012 number. Note that all parts of the URI are mandatory (e.g. you
4013 cannot omit "port" or "scheme").
4014
4015 Example:
4016 modules:
4017 ...
4018 mod_sip:
4019 always_record_route: false
4020 record_route: "sip:example.com;lr"
4021 routes:
4022 - "sip:example.com;lr"
4023 - "sip:sip.example.com;lr"
4024 flow_timeout_udp: 30 sec
4025 flow_timeout_tcp: 1 min
4026 via:
4027 - tls://sip-tls.example.com:5061
4028 - tcp://sip-tcp.example.com:5060
4029 - udp://sip-udp.example.com:5060
4030 ...
4031
4032 mod_stats
4033 This module adds support for XEP-0039: Statistics Gathering. This
4034 protocol allows you to retrieve the following statistics from your
4035 ejabberd server:
4036
4037 · Total number of registered users on the current virtual host
4038 (users/total).
4039
4040 · Total number of registered users on all virtual hosts
4041 (users/all-hosts/total).
4042
4043 · Total number of online users on the current virtual host
4044 (users/online).
4045
4046 · Total number of online users on all virtual hosts
4047 (users/all-hosts/online).
4048
4049 Note
4050 The protocol extension is deferred and seems like even a few
4051 clients that were supporting it are now abandoned. So using this
4052 module makes very little sense.
4053
4054 The module has no options.
4055
4056 mod_stream_mgmt
4057 This module adds support for XEP-0198: Stream Management. This protocol
4058 allows active management of an XML stream between two XMPP entities,
4059 including features for stanza acknowledgements and stream resumption.
4060
4061 Available options:
4062 ack_timeout: timeout()
4063 A time to wait for stanza acknowledgements. Setting it to
4064 infinity effectively disables the timeout. The default value is
4065 1 minute.
4066
4067 cache_life_time: timeout()
4068 Same as top-level cache_life_time option, but applied to this
4069 module only.
4070
4071 cache_size: pos_integer() | infinity
4072 Same as top-level cache_size option, but applied to this module
4073 only.
4074
4075 max_ack_queue: Size
4076 This option specifies the maximum number of unacknowledged
4077 stanzas queued for possible retransmission. When the limit is
4078 exceeded, the client session is terminated. The allowed values
4079 are positive integers and infinity. You should be careful when
4080 setting this value as it should not be set too low, otherwise,
4081 you could kill sessions in a loop, before they get the chance
4082 to finish proper session initiation. It should definitely be
4083 set higher that the size of the offline queue (for example at
4084 least 3 times the value of the max offline queue and never
4085 lower than 1000). The default value is 5000.
4086
4087 max_resume_timeout: timeout()
4088 A client may specify the period of time until a session times
4089 out if the connection is lost. During this period of time, the
4090 client may resume its session. This option limits the period of
4091 time a client is permitted to request. It must be set to a
4092 timeout equal to or larger than the default resume_timeout. By
4093 default, it is set to the same value as the resume_timeout
4094 option.
4095
4096 queue_type: ram | file
4097 Same as top-level queue_type option, but applied to this module
4098 only.
4099
4100 resend_on_timeout: true | false | if_offline
4101 If this option is set to true, any message stanzas that weren’t
4102 acknowledged by the client will be resent on session timeout.
4103 This behavior might often be desired, but could have unexpected
4104 results under certain circumstances. For example, a message
4105 that was sent to two resources might get resent to one of them
4106 if the other one timed out. Therefore, the default value for
4107 this option is false, which tells ejabberd to generate an error
4108 message instead. As an alternative, the option may be set to
4109 if_offline. In this case, unacknowledged messages are resent
4110 only if no other resource is online when the session times out.
4111 Otherwise, error messages are generated.
4112
4113 resume_timeout: timeout()
4114 This option configures the (default) period of time until a
4115 session times out if the connection is lost. During this period
4116 of time, a client may resume its session. Note that the client
4117 may request a different timeout value, see the
4118 max_resume_timeout option. Setting it to 0 effectively disables
4119 session resumption. The default value is 5 minutes.
4120
4121 mod_stun_disco
4122 This module allows XMPP clients to discover STUN/TURN services and to
4123 obtain temporary credentials for using them as per XEP-0215: External
4124 Service Discovery.
4125
4126 Available options:
4127 access: AccessName
4128 This option defines which access rule will be used to control
4129 who is allowed to discover STUN/TURN services and to request
4130 temporary credentials. The default value is local.
4131
4132 credentials_lifetime: timeout()
4133 The lifetime of temporary credentials offered to clients. If
4134 ejabberd’s built-in TURN service is used, TURN relays allocated
4135 using temporary credentials will be terminated shortly after
4136 the credentials expired. The default value is 12 hours. Note
4137 that restarting the ejabberd node invalidates any temporary
4138 credentials offered before the restart unless a secret is
4139 specified (see below).
4140
4141 offer_local_services: true | false
4142 This option specifies whether local STUN/TURN services
4143 configured as ejabberd listeners should be announced
4144 automatically. Note that this will not include TLS-enabled
4145 services, which must be configured manually using the services
4146 option (see below). For non-anonymous TURN services, temporary
4147 credentials will be offered to the client. The default value is
4148 true.
4149
4150 secret: Text
4151 The secret used for generating temporary credentials. If this
4152 option isn’t specified, a secret will be auto-generated.
4153 However, a secret must be specified explicitly if non-anonymous
4154 TURN services running on other ejabberd nodes and/or external
4155 TURN services are configured. Also note that auto-generated
4156 secrets are lost when the node is restarted, which invalidates
4157 any credentials offered before the restart. Therefore, it’s
4158 recommended to explicitly specify a secret if clients cache
4159 retrieved credentials (for later use) across service restarts.
4160
4161 services: [Service, ...]
4162 The list of services offered to clients. This list can include
4163 STUN/TURN services running on any ejabberd node and/or external
4164 services. However, if any listed TURN service not running on
4165 the local ejabberd node requires authentication, a secret must
4166 be specified explicitly, and must be shared with that service.
4167 This will only work with ejabberd’s built-in STUN/TURN server
4168 and with external servers that support the same REST API For
4169 Access To TURN Services. Unless the offer_local_services is set
4170 to false, the explicitly listed services will be offered in
4171 addition to those announced automatically.
4172
4173 host: Host
4174 The hostname or IP address the STUN/TURN service is
4175 listening on. For non-TLS services, it’s recommended to
4176 specify an IP address (to avoid additional DNS lookup
4177 latency on the client side). For TLS services, the hostname
4178 (or IP address) should match the certificate. Specifying
4179 the host option is mandatory.
4180
4181 port: 1..65535
4182 The port number the STUN/TURN service is listening on. The
4183 default port number is 3478 for non-TLS services and 5349
4184 for TLS services.
4185
4186 restricted: true | false
4187 This option determines whether temporary credentials for
4188 accessing the service are offered. The default is false for
4189 STUN/STUNS services and true for TURN/TURNS services.
4190
4191 transport: tcp | udp
4192 The transport protocol supported by the service. The
4193 default is udp for non-TLS services and tcp for TLS
4194 services.
4195
4196 type: stun | turn | stuns | turns
4197 The type of service. Must be stun or turn for non-TLS
4198 services, stuns or turns for TLS services. The default type
4199 is stun.
4200
4201 Example:
4202
4203 services:
4204 -
4205 host: 203.0.113.3
4206 port: 3478
4207 type: stun
4208 transport: udp
4209 restricted: false
4210 -
4211 host: 203.0.113.3
4212 port: 3478
4213 type: turn
4214 transport: udp
4215 restricted: true
4216 -
4217 host: 203.0.113.3
4218 port: 3478
4219 type: stun
4220 transport: tcp
4221 restricted: false
4222 -
4223 host: 203.0.113.3
4224 port: 3478
4225 type: turn
4226 transport: tcp
4227 restricted: true
4228 -
4229 host: server.example.com
4230 port: 5349
4231 type: stuns
4232 transport: tcp
4233 restricted: false
4234 -
4235 host: server.example.com
4236 port: 5349
4237 type: turns
4238 transport: tcp
4239 restricted: true
4240
4241 mod_time
4242 This module adds support for XEP-0202: Entity Time. In other words, the
4243 module reports server’s system time.
4244
4245 The module has no options.
4246
4247 mod_vcard
4248 This module allows end users to store and retrieve their vCard, and to
4249 retrieve other users vCards, as defined in XEP-0054: vcard-temp. The
4250 module also implements an uncomplicated Jabber User Directory based on
4251 the vCards of these users. Moreover, it enables the server to send its
4252 vCard when queried.
4253
4254 Available options:
4255 allow_return_all: true | false
4256 This option enables you to specify if search operations with
4257 empty input fields should return all users who added some
4258 information to their vCard. The default value is false.
4259
4260 cache_life_time: timeout()
4261 Same as top-level cache_life_time option, but applied to this
4262 module only.
4263
4264 cache_missed: true | false
4265 Same as top-level cache_missed option, but applied to this
4266 module only.
4267
4268 cache_size: pos_integer() | infinity
4269 Same as top-level cache_size option, but applied to this module
4270 only.
4271
4272 db_type: mnesia | sql | ldap
4273 Same as top-level default_db option, but applied to this module
4274 only.
4275
4276 host
4277 Deprecated. Use hosts instead.
4278
4279 hosts: [Host, ...]
4280 This option defines the Jabber IDs of the service. If the hosts
4281 option is not specified, the only Jabber ID will be the
4282 hostname of the virtual host with the prefix "vjud.". The
4283 keyword @HOST@ is replaced with the real virtual host name.
4284
4285 matches: pos_integer() | infinity
4286 With this option, the number of reported search results can be
4287 limited. If the option’s value is set to infinity, all search
4288 results are reported. The default value is 30.
4289
4290 name: Name
4291 The value of the service name. This name is only visible in
4292 some clients that support XEP-0030: Service Discovery. The
4293 default is vCard User Search.
4294
4295 search: true | false
4296 This option specifies whether the search functionality is
4297 enabled or not. If disabled, the options hosts, name and vcard
4298 will be ignored and the Jabber User Directory service will not
4299 appear in the Service Discovery item list. The default value is
4300 false.
4301
4302 use_cache: true | false
4303 Same as top-level use_cache option, but applied to this module
4304 only.
4305
4306 vcard: vCard
4307 A custom vCard of the server that will be displayed by some
4308 XMPP clients in Service Discovery. The value of vCard is a YAML
4309 map constructed from an XML representation of vCard. Since the
4310 representation has no attributes, the mapping is
4311 straightforward.
4312
4313 For example, the following XML representation of vCard:
4314
4315 <vCard xmlns='vcard-temp'>
4316 <FN>Conferences</FN>
4317 <ADR>
4318 <WORK/>
4319 <STREET>Elm Street</STREET>
4320 </ADR>
4321 </vCard>
4322
4323 will be translated to:
4324
4325 vcard:
4326 fn: Conferences
4327 adr:
4328 -
4329 work: true
4330 street: Elm Street
4331
4332 Available options for ldap backend:
4333 ldap_backups
4334 Same as top-level ldap_backups option, but applied to this
4335 module only.
4336
4337 ldap_base
4338 Same as top-level ldap_base option, but applied to this module
4339 only.
4340
4341 ldap_deref_aliases
4342 Same as top-level ldap_deref_aliases option, but applied to
4343 this module only.
4344
4345 ldap_encrypt
4346 Same as top-level ldap_encrypt option, but applied to this
4347 module only.
4348
4349 ldap_filter
4350 Same as top-level ldap_filter option, but applied to this
4351 module only.
4352
4353 ldap_password
4354 Same as top-level ldap_password option, but applied to this
4355 module only.
4356
4357 ldap_port
4358 Same as top-level ldap_port option, but applied to this module
4359 only.
4360
4361 ldap_rootdn
4362 Same as top-level ldap_rootdn option, but applied to this
4363 module only.
4364
4365 ldap_search_fields: {Name: Attribute, ...}
4366 This option defines the search form and the LDAP attributes to
4367 search within. Name is the name of a search form field which
4368 will be automatically translated by using the translation files
4369 (see msgs/*.msg for available words). Attribute is the LDAP
4370 attribute or the pattern %u.
4371
4372 The default is:
4373
4374 User: "%u"
4375 "Full Name": displayName
4376 "Given Name": givenName
4377 "Middle Name": initials
4378 "Family Name": sn
4379 Nickname: "%u"
4380 Birthday: birthDay
4381 Country: c
4382 City: l
4383 Email: mail
4384 "Organization Name": o
4385 "Organization Unit": ou
4386
4387 ldap_search_reported: {SearchField: VcardField}, ...}
4388 This option defines which search fields should be reported.
4389 SearchField is the name of a search form field which will be
4390 automatically translated by using the translation files (see
4391 msgs/*.msg for available words). VcardField is the vCard field
4392 name defined in the ldap_vcard_map option.
4393
4394 The default is:
4395
4396 "Full Name": FN
4397 "Given Name": FIRST
4398 "Middle Name": MIDDLE
4399 "Family Name": LAST
4400 "Nickname": NICKNAME
4401 "Birthday": BDAY
4402 "Country": CTRY
4403 "City": LOCALITY
4404 "Email": EMAIL
4405 "Organization Name": ORGNAME
4406 "Organization Unit": ORGUNIT
4407
4408 ldap_servers
4409 Same as top-level ldap_servers option, but applied to this
4410 module only.
4411
4412 ldap_tls_cacertfile
4413 Same as top-level ldap_tls_cacertfile option, but applied to
4414 this module only.
4415
4416 ldap_tls_certfile
4417 Same as top-level ldap_tls_certfile option, but applied to this
4418 module only.
4419
4420 ldap_tls_depth
4421 Same as top-level ldap_tls_depth option, but applied to this
4422 module only.
4423
4424 ldap_tls_verify
4425 Same as top-level ldap_tls_verify option, but applied to this
4426 module only.
4427
4428 ldap_uids
4429 Same as top-level ldap_uids option, but applied to this module
4430 only.
4431
4432 ldap_vcard_map: {Name: {Pattern, LDAPattributes}, ...}
4433 With this option you can set the table that maps LDAP
4434 attributes to vCard fields. Name is the type name of the vCard
4435 as defined in RFC 2426. Pattern is a string which contains
4436 pattern variables %u, %d or %s. LDAPattributes is the list
4437 containing LDAP attributes. The pattern variables %s will be
4438 sequentially replaced with the values of LDAP attributes from
4439 List_of_LDAP_attributes, %u will be replaced with the user part
4440 of a JID, and %d will be replaced with the domain part of a
4441 JID.
4442
4443 The default is:
4444
4445 NICKNAME: {"%u": []}
4446 FN: {"%s": [displayName]}
4447 LAST: {"%s": [sn]}
4448 FIRST: {"%s": [givenName]}
4449 MIDDLE: {"%s": [initials]}
4450 ORGNAME: {"%s": [o]}
4451 ORGUNIT: {"%s": [ou]}
4452 CTRY: {"%s": [c]}
4453 LOCALITY: {"%s": [l]}
4454 STREET: {"%s": [street]}
4455 REGION: {"%s": [st]}
4456 PCODE: {"%s": [postalCode]}
4457 TITLE: {"%s": [title]}
4458 URL: {"%s": [labeleduri]}
4459 DESC: {"%s": [description]}
4460 TEL: {"%s": [telephoneNumber]}
4461 EMAIL: {"%s": [mail]}
4462 BDAY: {"%s": [birthDay]}
4463 ROLE: {"%s": [employeeType]}
4464 PHOTO: {"%s": [jpegPhoto]}
4465
4466 Available options for mnesia backend:
4467 search_all_hosts: true | false
4468 Whether to perform search on all virtual hosts or not. The
4469 default value is true.
4470
4471 mod_vcard_xupdate
4472 The user’s client can store an avatar in the user vCard. The
4473 vCard-Based Avatars protocol (XEP-0153) provides a method for clients
4474 to inform the contacts what is the avatar hash value. However, simple
4475 or small clients may not implement that protocol.
4476
4477 If this module is enabled, all the outgoing client presence stanzas get
4478 automatically the avatar hash on behalf of the client. So, the contacts
4479 receive the presence stanzas with the Update Data described in XEP-0153
4480 as if the client would had inserted it itself. If the client had
4481 already included such element in the presence stanza, it is replaced
4482 with the element generated by ejabberd.
4483
4484 By enabling this module, each vCard modification produces a hash
4485 recalculation, and each presence sent by a client produces hash
4486 retrieval and a presence stanza rewrite. For this reason, enabling this
4487 module will introduce a computational overhead in servers with clients
4488 that change frequently their presence. However, the overhead is
4489 significantly reduced by the use of caching, so you probably don’t want
4490 to set use_cache to false.
4491
4492 The module depends on mod_vcard.
4493
4494 Note
4495 Nowadays XEP-0153 is used mostly as "read-only", i.e. modern
4496 clients don’t publish their avatars inside vCards. Thus in the
4497 majority of cases the module is only used along with mod_avatar
4498 module for providing backward compatibility.
4499
4500 Available options:
4501 cache_life_time: timeout()
4502 Same as top-level cache_life_time option, but applied to this
4503 module only.
4504
4505 cache_missed: true | false
4506 Same as top-level cache_missed option, but applied to this
4507 module only.
4508
4509 cache_size: pos_integer() | infinity
4510 Same as top-level cache_size option, but applied to this module
4511 only.
4512
4513 use_cache: true | false
4514 Same as top-level use_cache option, but applied to this module
4515 only.
4516
4517 mod_version
4518 This module implements XEP-0092: Software Version. Consequently, it
4519 answers ejabberd’s version when queried.
4520
4521 Available options:
4522 show_os: true | false
4523 Should the operating system be revealed or not. The default
4524 value is true.
4525
4527 This section describes options of all listeners in ejabberd 20.04
4528
4529 TODO
4530
4532 ProcessOne.
4533
4535 This document describes the configuration file of ejabberd 20.04.
4536 Configuration options of other ejabberd versions may differ
4537 significantly.
4538
4540 Report bugs to https://github.com/processone/ejabberd/issues
4541
4543 Default configuration file:
4544 https://github.com/processone/ejabberd/blob/20.04/ejabberd.yml.example
4545
4546 Main site: https://ejabberd.im
4547
4548 Documentation: https://docs.ejabberd.im
4549
4550 Configuration Guide: https://docs.ejabberd.im/admin/configuration
4551
4552 Source code: https://github.com/processone/ejabberd
4553
4555 Copyright (c) 2002-2020 ProcessOne.
4556
4557
4558
4559 05/19/2020 EJABBERD.YML(5)