You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
xmpp.chapril.org-ejabberd/man/ejabberd.yml.5

7617 lines
199 KiB

'\" t
.\" Title: ejabberd.yml
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 05/04/2022
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "EJABBERD\&.YML" "5" "05/04/2022" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ejabberd.yml \- main configuration file for ejabberd\&.
.SH "SYNOPSIS"
.sp
ejabberd\&.yml
.SH "DESCRIPTION"
.sp
The configuration file is written in YAML language\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
YAML is indentation sensitive, so make sure you respect indentation, or otherwise you will get pretty cryptic configuration errors\&.
.sp .5v
.RE
.sp
Logically, configuration options are split into 3 main categories: \fIModules\fR, \fIListeners\fR and everything else called \fITop Level\fR options\&. Thus this document is split into 3 main chapters describing each category separately\&. So, the contents of ejabberd\&.yml will typically look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
hosts:
\- example\&.com
\- domain\&.tld
loglevel: info
\&.\&.\&.
listen:
\-
port: 5222
module: ejabberd_c2s
\&.\&.\&.
modules:
mod_roster: {}
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
Any configuration error (such as syntax error, unknown option or invalid option value) is fatal in the sense that ejabberd will refuse to load the whole configuration file and will not start or will abort configuration reload\&.
.sp
All options can be changed in runtime by running \fIejabberdctl reload\-config\fR command\&. Configuration reload is atomic: either all options are accepted and applied simultaneously or the new configuration is refused without any impact on currently running configuration\&.
.sp
Some options can be specified for particular virtual host(s) only using \fIhost_config\fR or \fIappend_host_config\fR options\&. Such options are called \fIlocal\fR\&. Examples are \fImodules\fR, \fIauth_method\fR and \fIdefault_db\fR\&. The options that cannot be defined per virtual host are called \fIglobal\fR\&. Examples are \fIloglevel\fR, \fIcertfiles\fR and \fIlisten\fR\&. It is a configuration mistake to put \fIglobal\fR options under \fIhost_config\fR or \fIappend_host_config\fR section \- ejabberd will refuse to load such configuration\&.
.sp
It is not recommended to write ejabberd\&.yml from scratch\&. Instead it is better to start from "default" configuration file available at https://github\&.com/processone/ejabberd/blob/22\&.05/ejabberd\&.yml\&.example\&. Once you get ejabberd running you can start changing configuration options to meet your requirements\&.
.sp
Note that this document is intended to provide comprehensive description of all configuration options that can be consulted to understand the meaning of a particular option, its format and possible values\&. It will be quite hard to understand how to configure ejabberd by reading this document only \- for this purpose the reader is recommended to read online Configuration Guide available at https://docs\&.ejabberd\&.im/admin/configuration\&.
.SH "TOP LEVEL OPTIONS"
.sp
This section describes top level options of ejabberd\&.
.PP
\fBaccess_rules\fR: \fI{AccessName: {allow|deny: ACLRules|ACLName}}\fR
.RS 4
This option defines
Access Rules\&. Each access rule is assigned a name that can be referenced from other parts of the configuration file (mostly from
\fIaccess\fR
options of ejabberd modules)\&. Each rule definition may contain arbitrary number of
\fIallow\fR
or
\fIdeny\fR
sections, and each section may contain any number of ACL rules (see
\fIacl\fR
option)\&. There are no access rules defined by default\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
access_rules:
configure:
allow: admin
something:
deny: someone
allow: all
s2s_banned:
deny: problematic_hosts
deny: banned_forever
deny:
ip: 222\&.111\&.222\&.111/32
deny:
ip: 111\&.222\&.111\&.222/32
allow: all
xmlrpc_access:
allow:
user: peter@example\&.com
allow:
user: ivone@example\&.com
allow:
user: bot@example\&.com
ip: 10\&.0\&.0\&.0/24
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBacl\fR: \fI{ACLName: {ACLType: ACLValue}}\fR
.RS 4
The option defines access control lists: named sets of rules which are used to match against different targets (such as a JID or an IP address)\&. Every set of rules has name
\fIACLName\fR: it can be any string except
\fIall\fR
or
\fInone\fR
(those are predefined names for the rules that match all or nothing respectively)\&. The name
\fIACLName\fR
can be referenced from other parts of the configuration file, for example in
\fIaccess_rules\fR
option\&. The rules of
\fIACLName\fR
are represented by mapping
\fI{ACLType: ACLValue}\fR\&. These can be one of the following:
.PP
\fBip\fR: \fINetwork\fR
.RS 4
The rule matches any IP address from the
\fINetwork\fR\&.
.RE
.PP
\fBnode_glob\fR: \fIPattern\fR
.RS 4
Same as
\fInode_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBnode_regexp\fR: \fIuser_regexp@server_regexp\fR
.RS 4
The rule matches any JID with node part matching regular expression
\fIuser_regexp\fR
and server part matching regular expression
\fIserver_regexp\fR\&.
.RE
.PP
\fBresource\fR: \fIResource\fR
.RS 4
The rule matches any JID with a resource
\fIResource\fR\&.
.RE
.PP
\fBresource_glob\fR: \fIPattern\fR
.RS 4
Same as
\fIresource_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBresource_regexp\fR: \fIRegexp\fR
.RS 4
The rule matches any JID with a resource that matches regular expression
\fIRegexp\fR\&.
.RE
.PP
\fBserver\fR: \fIServer\fR
.RS 4
The rule matches any JID from server
\fIServer\fR\&. The value of
\fIServer\fR
must be a valid hostname or an IP address\&.
.RE
.PP
\fBserver_glob\fR: \fIPattern\fR
.RS 4
Same as
\fIserver_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBserver_regexp\fR: \fIRegexp\fR
.RS 4
The rule matches any JID from the server that matches regular expression
\fIRegexp\fR\&.
.RE
.PP
\fBuser\fR: \fIUsername\fR
.RS 4
If
\fIUsername\fR
is in the form of "user@server", the rule matches a JID against this value\&. Otherwise, if
\fIUsername\fR
is in the form of "user", the rule matches any JID that has
\fIUsername\fR
in the node part as long as the server part of this JID is any virtual host served by ejabberd\&.
.RE
.PP
\fBuser_glob\fR: \fIPattern\fR
.RS 4
Same as
\fIuser_regexp\fR, but matching is performed on a specified
\fIPattern\fR
according to the rules used by the Unix shell\&.
.RE
.PP
\fBuser_regexp\fR: \fIRegexp\fR
.RS 4
If
\fIRegexp\fR
is in the form of "regexp@server", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is equal to "server"\&. If
\fIRegexp\fR
is in the form of "regexp", the rule matches any JID with node part matching regular expression "regexp" as long as the server part of this JID is any virtual host served by ejabberd\&.
.RE
.RE
.PP
\fBacme\fR: \fIOptions\fR
.RS 4
ACME
configuration, to automatically obtain SSL certificates for the domains served by ejabberd, which means that certificate requests and renewals are performed to some CA server (aka "ACME server") in a fully automated mode\&. The
\fIOptions\fR
are:
.PP
\fBauto\fR: \fItrue | false\fR
.RS 4
Whether to automatically request certificates for all configured domains (that yet have no a certificate) on server start or configuration reload\&. The default is
\fItrue\fR\&.
.RE
.PP
\fBca_url\fR: \fIURL\fR
.RS 4
The ACME directory URL used as an entry point for the ACME server\&. The default value is
https://acme\-v02\&.api\&.letsencrypt\&.org/directory
\- the directory URL of Let\(cqs Encrypt authority\&.
.RE
.PP
\fBcert_type\fR: \fIrsa | ec\fR
.RS 4
A type of a certificate key\&. Available values are
\fIec\fR
and
\fIrsa\fR
for EC and RSA certificates respectively\&. It\(cqs better to have RSA certificates for the purpose of backward compatibility with legacy clients and servers, thus the default is
\fIrsa\fR\&.
.RE
.PP
\fBcontact\fR: \fI[Contact, \&.\&.\&.]\fR
.RS 4
A list of contact addresses (typically emails) where an ACME server will send notifications when problems occur\&. The value of
\fIContact\fR
must be in the form of "scheme:address" (e\&.g\&. "mailto:user@domain\&.tld")\&. The default is an empty list which means an ACME server will send no notices\&.
.RE
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
acme:
ca_url: https://acme\-v02\&.api\&.letsencrypt\&.org/directory
contact:
\- mailto:admin@domain\&.tld
\- mailto:bot@domain\&.tld
auto: true
cert_type: rsa
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBallow_contrib_modules\fR: \fItrue | false\fR
.RS 4
Whether to allow installation of third\-party modules or not\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBallow_multiple_connections\fR: \fItrue | false\fR
.RS 4
This option is only used when the anonymous mode is enabled\&. Setting it to
\fItrue\fR
means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect\&. This option is only useful in very special occasions\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBanonymous_protocol\fR: \fIlogin_anon | sasl_anon | both\fR
.RS 4
Define what anonymous protocol will be used:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIlogin_anon\fR
means that the anonymous login method will be used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIsasl_anon\fR
means that the SASL Anonymous method will be used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIboth\fR
means that SASL Anonymous and login anonymous are both enabled\&.
.RE
.RE
.sp
The default value is \fIsasl_anon\fR\&.
.PP
\fBapi_permissions\fR: \fI[Permission, \&.\&.\&.]\fR
.RS 4
Define the permissions for API access\&. Please consult the ejabberd Docs web → For Developers → ejabberd ReST API →
API Permissions\&.
.RE
.PP
\fBappend_host_config\fR: \fI{Host: Options}\fR
.RS 4
To define specific ejabberd modules in a virtual host, you can define the global
\fImodules\fR
option with the common modules, and later add specific modules to certain virtual hosts\&. To accomplish that,
\fIappend_host_config\fR
option can be used\&.
.RE
.PP
\fBauth_cache_life_time\fR: \fItimeout()\fR
.RS 4
Same as
\fIcache_life_time\fR, but applied to authentication cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBauth_cache_missed\fR: \fItrue | false\fR
.RS 4
Same as
\fIcache_missed\fR, but applied to authentication cache only\&. If not set, the value from
\fIcache_missed\fR
will be used\&.
.RE
.PP
\fBauth_cache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as
\fIcache_size\fR, but applied to authentication cache only\&. If not set, the value from
\fIcache_size\fR
will be used\&.
.RE
.PP
\fBauth_method\fR: \fI[mnesia | sql | anonymous | external | jwt | ldap | pam, \&.\&.\&.]\fR
.RS 4
A list of authentication methods to use\&. If several methods are defined, authentication is considered successful as long as authentication of at least one of the methods succeeds\&. The default value is
\fI[mnesia]\fR\&.
.RE
.PP
\fBauth_opts\fR: \fI[Option, \&.\&.\&.]\fR
.RS 4
This is used by the contributed module
\fIejabberd_auth_http\fR
that can be installed from the
ejabberd\-contrib
Git repository\&. Please refer to that module\(cqs README file for details\&.
.RE
.sp
\fINote\fR about the next option: improved in 20\&.01:
.PP
\fBauth_password_format\fR: \fIplain | scram\fR
.RS 4
The option defines in what format the users passwords are stored:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIplain\fR: The password is stored as plain text in the database\&. This is risky because the passwords can be read if your database gets compromised\&. This is the default value\&. This format allows clients to authenticate using: the old Jabber Non\-SASL (XEP\-0078), SASL PLAIN, SASL DIGEST\-MD5, and SASL SCRAM\-SHA\-1\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIscram\fR: The password is not stored, only some information that allows to verify the hash provided by the client\&. It is impossible to obtain the original plain password from the stored information; for this reason, when this value is configured it cannot be changed to plain anymore\&. This format allows clients to authenticate using: SASL PLAIN and SASL SCRAM\-SHA\-1\&. The default value is
\fIplain\fR\&.
.RE
.RE
.PP
\fBauth_scram_hash\fR: \fIsha | sha256 | sha512\fR
.RS 4
Hash algorithm that should be used to store password in SCRAM format\&. You shouldn\(cqt change this if you already have passwords generated with a different algorithm \- users that have such passwords will not be able to authenticate\&. The default value is
\fIsha\fR\&.
.RE
.PP
\fBauth_use_cache\fR: \fItrue | false\fR
.RS 4
Same as
\fIuse_cache\fR, but applied to authentication cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBc2s_cafile\fR: \fIPath\fR
.RS 4
Full path to a file containing one or more CA certificates in PEM format\&. All client certificates should be signed by one of these root CA certificates and should contain the corresponding JID(s) in
\fIsubjectAltName\fR
field\&. There is no default value\&.
.RE
.sp
You can use host_config to specify this option per\-vhost\&.
.sp
To set a specific file per listener, use the listener\(cqs cafile option\&. Please notice that \fIc2s_cafile\fR overrides the listener\(cqs \fIcafile\fR option\&.
.PP
\fBc2s_ciphers\fR: \fI[Cipher, \&.\&.\&.]\fR
.RS 4
A list of OpenSSL ciphers to use for c2s connections\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
c2s_ciphers:
\- HIGH
\- "!aNULL"
\- "!eNULL"
\- "!3DES"
\- "@STRENGTH"
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBc2s_dhfile\fR: \fIPath\fR
.RS 4
Full path to a file containing custom DH parameters to use for c2s connections\&. Such a file could be created with the command "openssl dhparam \-out dh\&.pem 2048"\&. If this option is not specified, 2048\-bit MODP Group with 256\-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2\&.3\&.
.RE
.PP
\fBc2s_protocol_options\fR: \fI[Option, \&.\&.\&.]\fR
.RS 4
List of general SSL options to use for c2s connections\&. These map to OpenSSL\(cqs
\fIset_options()\fR\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
c2s_protocol_options:
\- no_sslv3
\- cipher_server_preference
\- no_compression
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBc2s_tls_compression\fR: \fItrue | false\fR
.RS 4
Whether to enable or disable TLS compression for c2s connections\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBca_file\fR: \fIPath\fR
.RS 4
Path to a file of CA root certificates\&. The default is to use system defined file if possible\&.
.RE
.sp
For server connections, this \fIca_file\fR option is overridden by the s2s_cafile option\&.
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
The time of a cached item to keep in cache\&. Once it\(cqs expired, the corresponding item is erased from cache\&. The default value is
\fI1 hour\fR\&. Several modules have a similar option; and some core ejabberd parts support similar options too, see
\fIauth_cache_life_time\fR,
\fIoauth_cache_life_time\fR,
\fIrouter_cache_life_time\fR, and
\fIsm_cache_life_time\fR\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS 4
Whether or not to cache missed lookups\&. When there is an attempt to lookup for a value in a database and this value is not found and the option is set to
\fItrue\fR, this attempt will be cached and no attempts will be performed until the cache expires (see
\fIcache_life_time\fR)\&. Usually you don\(cqt want to change it\&. Default is
\fItrue\fR\&. Several modules have a similar option; and some core ejabberd parts support similar options too, see
\fIauth_cache_missed\fR,
\fIoauth_cache_missed\fR,
\fIrouter_cache_missed\fR, and
\fIsm_cache_missed\fR\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
A maximum number of items (not memory!) in cache\&. The rule of thumb, for all tables except rosters, you should set it to the number of maximum online users you expect\&. For roster multiply this number by 20 or so\&. If the cache size reaches this threshold, it\(cqs fully cleared, i\&.e\&. all items are deleted, and the corresponding warning is logged\&. You should avoid frequent cache clearance, because this degrades performance\&. The default value is
\fI1000\fR\&. Several modules have a similar option; and some core ejabberd parts support similar options too, see
\fIauth_cache_size\fR,
\fIoauth_cache_size\fR,
\fIrouter_cache_size\fR, and
\fIsm_cache_size\fR\&.
.RE
.PP
\fBcaptcha_cmd\fR: \fIPath\fR
.RS 4
Full path to a script that generates
CAPTCHA
images\&. There is no default value: when this option is not set, CAPTCHA functionality is completely disabled\&.
.RE
.PP
\fBcaptcha_host\fR: \fIString\fR
.RS 4
Deprecated\&. Use
\fIcaptcha_url\fR
instead\&.
.RE
.PP
\fBcaptcha_limit\fR: \fIpos_integer() | infinity\fR
.RS 4
Maximum number of
CAPTCHA
generated images per minute for any given JID\&. The option is intended to protect the server from CAPTCHA DoS\&. The default value is
\fIinfinity\fR\&.
.RE
.PP
\fBcaptcha_url\fR: \fIURL\fR
.RS 4
An URL where
CAPTCHA
requests should be sent\&. NOTE: you need to configure
\fIrequest_handlers\fR
for
\fIejabberd_http\fR
listener as well\&. There is no default value\&.
.RE
.PP
\fBcertfiles\fR: \fI[Path, \&.\&.\&.]\fR
.RS 4
The option accepts a list of file paths (optionally with wildcards) containing either PEM certificates or PEM private keys\&. At startup or configuration reload, ejabberd reads all certificates from these files, sorts them, removes duplicates, finds matching private keys and then rebuilds full certificate chains for the use in TLS connections\&. Use this option when TLS is enabled in either of ejabberd listeners:
\fIejabberd_c2s\fR,
\fIejabberd_http\fR
and so on\&. NOTE: if you modify the certificate files or change the value of the option, run
\fIejabberdctl reload\-config\fR
in order to rebuild and reload the certificate chains\&.
.sp
If you use
Let\(cqs Encrypt
certificates for your domain "domain\&.tld", the configuration will look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
certfiles:
\- /etc/letsencrypt/live/domain\&.tld/fullchain\&.pem
\- /etc/letsencrypt/live/domain\&.tld/privkey\&.pem
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBcluster_backend\fR: \fIBackend\fR
.RS 4
A database backend to use for storing information about cluster\&. The only available value so far is
\fImnesia\fR\&.
.RE
.PP
\fBcluster_nodes\fR: \fI[Node, \&.\&.\&.]\fR
.RS 4
A list of Erlang nodes to connect on ejabberd startup\&. This option is mostly intended for ejabberd customization and sophisticated setups\&. The default value is an empty list\&.
.RE
.PP
\fBdefault_db\fR: \fImnesia | sql\fR
.RS 4
Default persistent storage for ejabberd\&. Modules and other components (e\&.g\&. authentication) may have its own value\&. The default value is
\fImnesia\fR\&.
.RE
.PP
\fBdefault_ram_db\fR: \fImnesia | redis | sql\fR
.RS 4
Default volatile (in\-memory) storage for ejabberd\&. Modules and other components (e\&.g\&. session management) may have its own value\&. The default value is
\fImnesia\fR\&.
.RE
.PP
\fBdefine_macro\fR: \fI{MacroName: MacroValue}\fR
.RS 4
Defines a macro\&. The value can be any valid arbitrary YAML value\&. For convenience, it\(cqs recommended to define a
\fIMacroName\fR
in capital letters\&. Duplicated macros are not allowed\&. Macros are processed after additional configuration files have been included, so it is possible to use macros that are defined in configuration files included before the usage\&. It is possible to use a
\fIMacroValue\fR
in the definition of another macro\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
define_macro:
DEBUG: debug
LOG_LEVEL: DEBUG
USERBOB:
user: bob@localhost
loglevel: LOG_LEVEL
acl:
admin: USERBOB
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBdisable_sasl_mechanisms\fR: \fI[Mechanism, \&.\&.\&.]\fR
.RS 4
Specify a list of SASL mechanisms (such as
\fIDIGEST\-MD5\fR
or
\fISCRAM\-SHA1\fR) that should not be offered to the client\&. For convenience, the value of
\fIMechanism\fR
is case\-insensitive\&. The default value is an empty list, i\&.e\&. no mechanisms are disabled by default\&.
.RE
.PP
\fBdomain_balancing\fR: \fI{Domain: Options}\fR
.RS 4
An algorithm to load balance the components that are plugged on an ejabberd cluster\&. It means that you can plug one or several instances of the same component on each ejabberd node and that the traffic will be automatically distributed\&. The algorithm to deliver messages to the component(s) can be specified by this option\&. For any component connected as
\fIDomain\fR, available
\fIOptions\fR
are:
.PP
\fBcomponent_number\fR: \fI2\&.\&.1000\fR
.RS 4
The number of components to balance\&.
.RE
.PP
\fBtype\fR: \fIrandom | source | destination | bare_source | bare_destination\fR
.RS 4
How to deliver stanzas to connected components:
\fIrandom\fR
\- an instance is chosen at random;
\fIdestination\fR
\- an instance is chosen by the full JID of the packet\(cqs
\fIto\fR
attribute;
\fIsource\fR
\- by the full JID of the packet\(cqs
\fIfrom\fR
attribute;
\fIbare_destination\fR
\- by the the bare JID (without resource) of the packet\(cqs
\fIto\fR
attribute;
\fIbare_source\fR
\- by the bare JID (without resource) of the packet\(cqs
\fIfrom\fR
attribute is used\&. The default value is
\fIrandom\fR\&.
.RE
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
domain_balancing:
component\&.domain\&.tld:
type: destination
component_number: 5
transport\&.example\&.org:
type: bare_source
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBext_api_headers\fR: \fIHeaders\fR
.RS 4
String of headers (separated with commas
\fI,\fR) that will be provided by ejabberd when sending ReST requests\&. The default value is an empty string of headers:
\fI""\fR\&.
.RE
.PP
\fBext_api_http_pool_size\fR: \fIpos_integer()\fR
.RS 4
Define the size of the HTTP pool, that is, the maximum number of sessions that the ejabberd ReST service will handle simultaneously\&. The default value is:
\fI100\fR\&.
.RE
.PP
\fBext_api_path_oauth\fR: \fIPath\fR
.RS 4
Define the base URI path when performing OAUTH ReST requests\&. The default value is:
\fI"/oauth"\fR\&.
.RE
.PP
\fBext_api_url\fR: \fIURL\fR
.RS 4
Define the base URI when performing ReST requests\&. The default value is:
\fI"http://localhost/api"\fR\&.
.RE
.PP
\fBextauth_pool_name\fR: \fIName\fR
.RS 4
Define the pool name appendix, so the full pool name will be
\fIextauth_pool_Name\fR\&. The default value is the hostname\&.
.RE
.PP
\fBextauth_pool_size\fR: \fISize\fR
.RS 4
The option defines the number of instances of the same external program to start for better load balancing\&. The default is the number of available CPU cores\&.
.RE
.PP
\fBextauth_program\fR: \fIPath\fR
.RS 4
Indicate in this option the full path to the external authentication script\&. The script must be executable by ejabberd\&.
.RE
.PP
\fBfqdn\fR: \fIDomain\fR
.RS 4
A fully qualified domain name that will be used in SASL DIGEST\-MD5 authentication\&. The default is detected automatically\&.
.RE
.PP
\fBhide_sensitive_log_data\fR: \fItrue | false\fR
.RS 4
A privacy option to not log sensitive data (mostly IP addresses)\&. The default value is
\fIfalse\fR
for backward compatibility\&.
.RE
.PP
\fBhost_config\fR: \fI{Host: Options}\fR
.RS 4
The option is used to redefine
\fIOptions\fR
for virtual host
\fIHost\fR\&. In the example below LDAP authentication method will be used on virtual host
\fIdomain\&.tld\fR
and SQL method will be used on virtual host
\fIexample\&.org\fR\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
hosts:
\- domain\&.tld
\- example\&.org
auth_method:
\- sql
host_config:
domain\&.tld:
auth_method:
\- ldap
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBhosts\fR: \fI[Domain1, Domain2, \&.\&.\&.]\fR
.RS 4
The option defines a list containing one or more domains that
\fIejabberd\fR
will serve\&. This is a
\fBmandatory\fR
option\&.
.RE
.PP
\fBinclude_config_file\fR: \fI[Filename, \&.\&.\&.] | {Filename: Options}\fR
.RS 4
Read additional configuration from
\fIFilename\fR\&. If the value is provided in
\fI{Filename: Options}\fR
format, the
\fIOptions\fR
must be one of the following:
.PP
\fBallow_only\fR: \fI[OptionName, \&.\&.\&.]\fR
.RS 4
Allows only the usage of those options in the included file
\fIFilename\fR\&. The options that do not match this criteria are not accepted\&. The default value is to include all options\&.
.RE
.PP
\fBdisallow\fR: \fI[OptionName, \&.\&.\&.]\fR
.RS 4
Disallows the usage of those options in the included file
\fIFilename\fR\&. The options that match this criteria are not accepted\&. The default value is an empty list\&.
.RE
.RE
.PP
\fBjwt_auth_only_rule\fR: \fIAccessName\fR
.RS 4
This ACL rule defines accounts that can use only this auth method, even if others are also defined in the ejabberd configuration file\&. In other words: if there are several auth methods enabled for this host (JWT, SQL, \&...), users that match this rule can only use JWT\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBjwt_jid_field\fR: \fIFieldName\fR
.RS 4
By default, the JID is defined in the
\fI"jid"\fR
JWT field\&. This option allows to specify other JWT field name where the JID is defined\&.
.RE
.PP
\fBjwt_key\fR: \fIFilePath\fR
.RS 4
Path to the file that contains the JWK Key\&. The default value is
\fIundefined\fR\&.
.RE
.PP
\fBlanguage\fR: \fILanguage\fR
.RS 4
The option defines the default language of server strings that can be seen by XMPP clients\&. If an XMPP client does not possess
\fIxml:lang\fR
attribute, the specified language is used\&. The default value is
\fI"en"\fR\&.
.RE
.PP
\fBldap_backups\fR: \fI[Host, \&.\&.\&.]\fR
.RS 4
A list of IP addresses or DNS names of LDAP backup servers\&. When no servers listed in
\fIldap_servers\fR
option are reachable, ejabberd will try to connect to these backup servers\&. The default is an empty list, i\&.e\&. no backup servers specified\&. WARNING: ejabberd doesn\(cqt try to reconnect back to the main servers when they become operational again, so the only way to restore these connections is to restart ejabberd\&. This limitation might be fixed in future releases\&.
.RE
.PP
\fBldap_base\fR: \fIBase\fR
.RS 4
LDAP base directory which stores users accounts\&. There is no default value: you must set the option in order for LDAP connections to work properly\&.
.RE
.PP
\fBldap_deref_aliases\fR: \fInever | always | finding | searching\fR
.RS 4
Whether to dereference aliases or not\&. The default value is
\fInever\fR\&.
.RE
.PP
\fBldap_dn_filter\fR: \fI{Filter: FilterAttrs}\fR
.RS 4
This filter is applied on the results returned by the main filter\&. The filter performs an additional LDAP lookup to make the complete result\&. This is useful when you are unable to define all filter rules in
\fIldap_filter\fR\&. You can define "%u", "%d", "%s" and "%D" pattern variables in
\fIFilter\fR: "%u" is replaced by a user\(cqs part of the JID, "%d" is replaced by the corresponding domain (virtual host), all "%s" variables are consecutively replaced by values from the attributes in
\fIFilterAttrs\fR
and "%D" is replaced by Distinguished Name from the result set\&. There is no default value, which means the result is not filtered\&. WARNING: Since this filter makes additional LDAP lookups, use it only as the last resort: try to define all filter rules in
\fIldap_filter\fR
option if possible\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
ldap_dn_filter:
"(&(name=%s)(owner=%D)(user=%u@%d))": [sn]
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBldap_encrypt\fR: \fItls | none\fR
.RS 4
Whether to encrypt LDAP connection using TLS or not\&. The default value is
\fInone\fR\&. NOTE: STARTTLS encryption is not supported\&.
.RE
.PP
\fBldap_filter\fR: \fIFilter\fR
.RS 4
An LDAP filter as defined in
RFC4515\&. There is no default value\&. Example: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))"\&. NOTE: don\(cqt forget to close brackets and don\(cqt use superfluous whitespaces\&. Also you must not use "uid" attribute in the filter because this attribute will be appended to the filter automatically\&.
.RE
.PP
\fBldap_password\fR: \fIPassword\fR
.RS 4
Bind password\&. The default value is an empty string\&.
.RE
.PP
\fBldap_port\fR: \fI1\&.\&.65535\fR
.RS 4
Port to connect to your LDAP server\&. The default port is
\fI389\fR
if encryption is disabled and
\fI636\fR
if encryption is enabled\&.
.RE
.PP
\fBldap_rootdn\fR: \fIRootDN\fR
.RS 4
Bind Distinguished Name\&. The default value is an empty string, which means "anonymous connection"\&.
.RE
.PP
\fBldap_servers\fR: \fI[Host, \&.\&.\&.]\fR
.RS 4
A list of IP addresses or DNS names of your LDAP servers\&. The default value is
\fI[localhost]\fR\&.
.RE
.PP
\fBldap_tls_cacertfile\fR: \fIPath\fR
.RS 4
A path to a file containing PEM encoded CA certificates\&. This option is required when TLS verification is enabled\&.
.RE
.PP
\fBldap_tls_certfile\fR: \fIPath\fR
.RS 4
A path to a file containing PEM encoded certificate along with PEM encoded private key\&. This certificate will be provided by ejabberd when TLS enabled for LDAP connections\&. There is no default value, which means no client certificate will be sent\&.
.RE
.PP
\fBldap_tls_depth\fR: \fINumber\fR
.RS 4
Specifies the maximum verification depth when TLS verification is enabled, i\&.e\&. how far in a chain of certificates the verification process can proceed before the verification is considered to be failed\&. Peer certificate = 0, CA certificate = 1, higher level CA certificate = 2, etc\&. The value
\fI2\fR
thus means that a chain can at most contain peer cert, CA cert, next CA cert, and an additional CA cert\&. The default value is
\fI1\fR\&.
.RE
.PP
\fBldap_tls_verify\fR: \fIfalse | soft | hard\fR
.RS 4
This option specifies whether to verify LDAP server certificate or not when TLS is enabled\&. When
\fIhard\fR
is set, ejabberd doesn\(cqt proceed if the certificate is invalid\&. When
\fIsoft\fR
is set, ejabberd proceeds even if the check has failed\&. The default is
\fIfalse\fR, which means no checks are performed\&.
.RE
.PP
\fBldap_uids\fR: \fI[Attr] | {Attr: AttrFormat}\fR
.RS 4
LDAP attributes which hold a list of attributes to use as alternatives for getting the JID, where
\fIAttr\fR
is an LDAP attribute which holds the user\(cqs part of the JID and
\fIAttrFormat\fR
must contain one and only one pattern variable "%u" which will be replaced by the user\(cqs part of the JID\&. For example, "%u@example\&.org"\&. If the value is in the form of
\fI[Attr]\fR
then
\fIAttrFormat\fR
is assumed to be "%u"\&.
.RE
.PP
\fBlisten\fR: \fI[Options, \&.\&.\&.]\fR
.RS 4
The option for listeners configuration\&. See the
Listen Modules
section for details\&.
.RE
.PP
\fBlog_rotate_count\fR: \fINumber\fR
.RS 4
The number of rotated log files to keep\&. The default value is
\fI1\fR, which means that only keeps
ejabberd\&.log\&.0,
error\&.log\&.0
and
crash\&.log\&.0\&.
.RE
.PP
\fBlog_rotate_size\fR: \fIpos_integer() | infinity\fR
.RS 4
The size (in bytes) of a log file to trigger rotation\&. If set to
\fIinfinity\fR, log rotation is disabled\&. The default value is
\fI10485760\fR
(that is, 10 Mb)\&.
.RE
.PP
\fBloglevel\fR: \fInone | emergency | alert | critical | error | warning | notice | info | debug\fR
.RS 4
Verbosity of log files generated by ejabberd\&. The default value is
\fIinfo\fR\&. NOTE: previous versions of ejabberd had log levels defined in numeric format (\fI0\&.\&.5\fR)\&. The numeric values are still accepted for backward compatibility, but are not recommended\&.
.RE
.PP
\fBmax_fsm_queue\fR: \fISize\fR
.RS 4
This option specifies the maximum number of elements in the queue of the FSM (Finite State Machine)\&. Roughly speaking, each message in such queues represents one XML stanza queued to be sent into its relevant outgoing stream\&. If queue size reaches the limit (because, for example, the receiver of stanzas is too slow), the FSM and the corresponding connection (if any) will be terminated and error message will be logged\&. The reasonable value for this option depends on your hardware configuration\&. The allowed values are positive integers\&. The default value is
\fI10000\fR\&.
.RE
.PP
\fBmodules\fR: \fI{Module: Options}\fR
.RS 4
The option for modules configuration\&. See
Modules
section for details\&.
.RE
.PP
\fBnegotiation_timeout\fR: \fItimeout()\fR
.RS 4
Time to wait for an XMPP stream negotiation to complete\&. When timeout occurs, the corresponding XMPP stream is closed\&. The default value is
\fI30\fR
seconds\&.
.RE
.PP
\fBnet_ticktime\fR: \fItimeout()\fR
.RS 4
This option can be used to tune tick time parameter of
\fInet_kernel\fR\&. It tells Erlang VM how often nodes should check if intra\-node communication was not interrupted\&. This option must have identical value on all nodes, or it will lead to subtle bugs\&. Usually leaving default value of this is option is best, tweak it only if you know what you are doing\&. The default value is
\fI1 minute\fR\&.
.RE
.PP
\fBnew_sql_schema\fR: \fItrue | false\fR
.RS 4
Whether to use
\fInew\fR
SQL schema\&. All schemas are located at
https://github\&.com/processone/ejabberd/tree/22\&.05/sql\&. There are two schemas available\&. The default legacy schema allows to store one XMPP domain into one ejabberd database\&. The
\fInew\fR
schema allows to handle several XMPP domains in a single ejabberd database\&. Using this
\fInew\fR
schema is best when serving several XMPP domains and/or changing domains from time to time\&. This avoid need to manage several databases and handle complex configuration changes\&. The default depends on configuration flag
\fI\-\-enable\-new\-sql\-schema\fR
which is set at compile time\&.
.RE
.PP
\fBoauth_access\fR: \fIAccessName\fR
.RS 4
By default creating OAuth tokens is not allowed\&. To define which users can create OAuth tokens, you can refer to an ejabberd access rule in the
\fIoauth_access\fR
option\&. Use
\fIall\fR
to allow everyone to create tokens\&.
.RE
.PP
\fBoauth_cache_life_time\fR: \fItimeout()\fR
.RS 4
Same as
\fIcache_life_time\fR, but applied to OAuth cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBoauth_cache_missed\fR: \fItrue | false\fR
.RS 4
Same as
\fIcache_missed\fR, but applied to OAuth cache only\&. If not set, the value from
\fIcache_missed\fR
will be used\&.
.RE
.sp
\fINote\fR about the next option: added in 21\&.01:
.PP
\fBoauth_cache_rest_failure_life_time\fR: \fItimeout()\fR
.RS 4
The time that a failure in OAuth ReST is cached\&. The default value is
\fIinfinity\fR\&.
.RE
.PP
\fBoauth_cache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as
\fIcache_size\fR, but applied to OAuth cache only\&. If not set, the value from
\fIcache_size\fR
will be used\&.
.RE
.PP
\fBoauth_client_id_check\fR: \fIallow | db | deny\fR
.RS 4
Define whether the client authentication is always allowed, denied, or it will depend if the client ID is present in the database\&. The default value is
\fIallow\fR\&.
.RE
.PP
\fBoauth_db_type\fR: \fImnesia | sql\fR
.RS 4
Database backend to use for OAuth authentication\&. The default value is picked from
\fIdefault_db\fR
option, or if it\(cqs not set,
\fImnesia\fR
will be used\&.
.RE
.PP
\fBoauth_expire\fR: \fItimeout()\fR
.RS 4
Time during which the OAuth token is valid, in seconds\&. After that amount of time, the token expires and the delegated credential cannot be used and is removed from the database\&. The default is
\fI4294967\fR
seconds\&.
.RE
.PP
\fBoauth_use_cache\fR: \fItrue | false\fR
.RS 4
Same as
\fIuse_cache\fR, but applied to OAuth cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBoom_killer\fR: \fItrue | false\fR
.RS 4
Enable or disable OOM (out\-of\-memory) killer\&. When system memory raises above the limit defined in
\fIoom_watermark\fR
option, ejabberd triggers OOM killer to terminate most memory consuming Erlang processes\&. Note that in order to maintain functionality, ejabberd only attempts to kill transient processes, such as those managing client sessions, s2s or database connections\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBoom_queue\fR: \fISize\fR
.RS 4
Trigger OOM killer when some of the running Erlang processes have messages queue above this
\fISize\fR\&. Note that such processes won\(cqt be killed if
\fIoom_killer\fR
option is set to
\fIfalse\fR
or if
\fIoom_watermark\fR
is not reached yet\&.
.RE
.PP
\fBoom_watermark\fR: \fIPercent\fR
.RS 4
A percent of total system memory consumed at which OOM killer should be activated with some of the processes possibly be killed (see
\fIoom_killer\fR
option)\&. Later, when memory drops below this
\fIPercent\fR, OOM killer is deactivated\&. The default value is
\fI80\fR
percents\&.
.RE
.PP
\fBoutgoing_s2s_families\fR: \fI[ipv4 | ipv6, \&.\&.\&.]\fR
.RS 4
Specify which address families to try, in what order\&. The default is
\fI[ipv4, ipv6]\fR
which means it first tries connecting with IPv4, if that fails it tries using IPv6\&.
.RE
.sp
\fINote\fR about the next option: added in 20\&.12:
.PP
\fBoutgoing_s2s_ipv4_address\fR: \fIAddress\fR
.RS 4
Specify the IPv4 address that will be used when establishing an outgoing S2S IPv4 connection, for example "127\&.0\&.0\&.1"\&. The default value is
\fIundefined\fR\&.
.RE
.sp
\fINote\fR about the next option: added in 20\&.12:
.PP
\fBoutgoing_s2s_ipv6_address\fR: \fIAddress\fR
.RS 4
Specify the IPv6 address that will be used when establishing an outgoing S2S IPv6 connection, for example "::FFFF:127\&.0\&.0\&.1"\&. The default value is
\fIundefined\fR\&.
.RE
.PP
\fBoutgoing_s2s_port\fR: \fI1\&.\&.65535\fR
.RS 4
A port number to use for outgoing s2s connections when the target server doesn\(cqt have an SRV record\&. The default value is
\fI5269\fR\&.
.RE
.PP
\fBoutgoing_s2s_timeout\fR: \fItimeout()\fR
.RS 4
The timeout in seconds for outgoing S2S connection attempts\&. The default value is
\fI10\fR
seconds\&.
.RE
.PP
\fBpam_service\fR: \fIName\fR
.RS 4
This option defines the PAM service name\&. Refer to the PAM documentation of your operation system for more information\&. The default value is
\fIejabberd\fR\&.
.RE
.PP
\fBpam_userinfotype\fR: \fIusername | jid\fR
.RS 4
This option defines what type of information about the user ejabberd provides to the PAM service: only the username, or the user\(cqs JID\&. Default is
\fIusername\fR\&.
.RE
.PP
\fBpgsql_users_number_estimate\fR: \fItrue | false\fR
.RS 4
Whether to use PostgreSQL estimation when counting registered users\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBqueue_dir\fR: \fIDirectory\fR
.RS 4
If
\fIqueue_type\fR
option is set to
\fIfile\fR, use this
\fIDirectory\fR
to store file queues\&. The default is to keep queues inside Mnesia directory\&.
.RE
.PP
\fBqueue_type\fR: \fIram | file\fR
.RS 4
Default type of queues in ejabberd\&. Modules may have its own value of the option\&. The value of
\fIram\fR
means that queues will be kept in memory\&. If value
\fIfile\fR
is set, you may also specify directory in
\fIqueue_dir\fR
option where file queues will be placed\&. The default value is
\fIram\fR\&.
.RE
.PP
\fBredis_connect_timeout\fR: \fItimeout()\fR
.RS 4
A timeout to wait for the connection to be re\-established to the Redis server\&. The default is
\fI1 second\fR\&.
.RE
.PP
\fBredis_db\fR: \fINumber\fR
.RS 4
Redis database number\&. The default is
\fI0\fR\&.
.RE
.PP
\fBredis_password\fR: \fIPassword\fR
.RS 4
The password to the Redis server\&. The default is an empty string, i\&.e\&. no password\&.
.RE
.PP
\fBredis_pool_size\fR: \fINumber\fR
.RS 4
The number of simultaneous connections to the Redis server\&. The default value is
\fI10\fR\&.
.RE
.PP
\fBredis_port\fR: \fI1\&.\&.65535\fR
.RS 4
The port where the Redis server is accepting connections\&. The default is
\fI6379\fR\&.
.RE
.PP
\fBredis_queue_type\fR: \fIram | file\fR
.RS 4
The type of request queue for the Redis server\&. See description of
\fIqueue_type\fR
option for the explanation\&. The default value is the value defined in
\fIqueue_type\fR
or
\fIram\fR
if the latter is not set\&.
.RE
.PP
\fBredis_server\fR: \fIHostname\fR
.RS 4
A hostname or an IP address of the Redis server\&. The default is
\fIlocalhost\fR\&.
.RE
.PP
\fBregistration_timeout\fR: \fItimeout()\fR
.RS 4
This is a global option for module
\fImod_register\fR\&. It limits the frequency of registrations from a given IP or username\&. So, a user that tries to register a new account from the same IP address or JID during this time after their previous registration will receive an error with the corresponding explanation\&. To disable this limitation, set the value to
\fIinfinity\fR\&. The default value is
\fI600 seconds\fR\&.
.RE
.PP
\fBresource_conflict\fR: \fIsetresource | closeold | closenew\fR
.RS 4
NOTE: this option is deprecated and may be removed anytime in the future versions\&. The possible values match exactly the three possibilities described in
XMPP Core: section 7\&.7\&.2\&.2\&. The default value is
\fIcloseold\fR\&. If the client uses old Jabber Non\-SASL authentication (XEP\-0078), then this option is not respected, and the action performed is
\fIcloseold\fR\&.
.RE
.PP
\fBrouter_cache_life_time\fR: \fItimeout()\fR
.RS 4
Same as
\fIcache_life_time\fR, but applied to routing table cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBrouter_cache_missed\fR: \fItrue | false\fR
.RS 4
Same as
\fIcache_missed\fR, but applied to routing table cache only\&. If not set, the value from
\fIcache_missed\fR
will be used\&.
.RE
.PP
\fBrouter_cache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as
\fIcache_size\fR, but applied to routing table cache only\&. If not set, the value from
\fIcache_size\fR
will be used\&.
.RE
.PP
\fBrouter_db_type\fR: \fImnesia | redis | sql\fR
.RS 4
Database backend to use for routing information\&. The default value is picked from
\fIdefault_ram_db\fR
option, or if it\(cqs not set,
\fImnesia\fR
will be used\&.
.RE
.PP
\fBrouter_use_cache\fR: \fItrue | false\fR
.RS 4
Same as
\fIuse_cache\fR, but applied to routing table cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBrpc_timeout\fR: \fItimeout()\fR
.RS 4
A timeout for remote function calls between nodes in an ejabberd cluster\&. You should probably never change this value since those calls are used for internal needs only\&. The default value is
\fI5\fR
seconds\&.
.RE
.PP
\fBs2s_access\fR: \fIAccess\fR
.RS 4
This
Access Rule
defines to what remote servers can s2s connections be established\&. The default value is
\fIall\fR; no restrictions are applied, it is allowed to connect s2s to/from all remote servers\&.
.RE
.PP
\fBs2s_cafile\fR: \fIPath\fR
.RS 4
A path to a file with CA root certificates that will be used to authenticate s2s connections\&. If not set, the value of
ca_file
will be used\&.
.RE
.sp
You can use host_config to specify this option per\-vhost\&.
.PP
\fBs2s_ciphers\fR: \fI[Cipher, \&.\&.\&.]\fR
.RS 4
A list of OpenSSL ciphers to use for s2s connections\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
s2s_ciphers:
\- HIGH
\- "!aNULL"
\- "!eNULL"
\- "!3DES"
\- "@STRENGTH"
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBs2s_dhfile\fR: \fIPath\fR
.RS 4
Full path to a file containing custom DH parameters to use for s2s connections\&. Such a file could be created with the command "openssl dhparam \-out dh\&.pem 2048"\&. If this option is not specified, 2048\-bit MODP Group with 256\-bit Prime Order Subgroup will be used as defined in RFC5114 Section 2\&.3\&.
.RE
.PP
\fBs2s_dns_retries\fR: \fINumber\fR
.RS 4
DNS resolving retries\&. The default value is
\fI2\fR\&.
.RE
.PP
\fBs2s_dns_timeout\fR: \fItimeout()\fR
.RS 4
The timeout for DNS resolving\&. The default value is
\fI10\fR
seconds\&.
.RE
.PP
\fBs2s_max_retry_delay\fR: \fItimeout()\fR
.RS 4
The maximum allowed delay for s2s connection retry to connect after a failed connection attempt\&. The default value is
\fI300\fR
seconds (5 minutes)\&.
.RE
.PP
\fBs2s_protocol_options\fR: \fI[Option, \&.\&.\&.]\fR
.RS 4
List of general SSL options to use for s2s connections\&. These map to OpenSSL\(cqs
\fIset_options()\fR\&. The default value is shown in the example below:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
s2s_protocol_options:
\- no_sslv3
\- cipher_server_preference
\- no_compression
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBs2s_queue_type\fR: \fIram | file\fR
.RS 4
The type of a queue for s2s packets\&. See description of
\fIqueue_type\fR
option for the explanation\&. The default value is the value defined in
\fIqueue_type\fR
or
\fIram\fR
if the latter is not set\&.
.RE
.PP
\fBs2s_timeout\fR: \fItimeout()\fR
.RS 4
A time to wait before closing an idle s2s connection\&. The default value is
\fI10 minutes\fR\&.
.RE
.PP
\fBs2s_tls_compression\fR: \fItrue | false\fR
.RS 4
Whether to enable or disable TLS compression for s2s connections\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBs2s_use_starttls\fR: \fItrue | false | optional | required\fR
.RS 4
Whether to use STARTTLS for s2s connections\&. The value of
\fIfalse\fR
means STARTTLS is prohibited\&. The value of
\fItrue\fR
or
\fIoptional\fR
means STARTTLS is enabled but plain connections are still allowed\&. And the value of
\fIrequired\fR
means that only STARTTLS connections are allowed\&. The default value is
\fIfalse\fR
(for historical reasons)\&.
.RE
.PP
\fBs2s_zlib\fR: \fItrue | false\fR
.RS 4
Whether to use
\fIzlib\fR
compression (as defined in
XEP\-0138) or not\&. The default value is
\fIfalse\fR\&. WARNING: this type of compression is nowadays considered insecure\&.
.RE
.PP
\fBshaper\fR: \fI{ShaperName: Rate}\fR
.RS 4
The option defines a set of shapers\&. Every shaper is assigned a name
\fIShaperName\fR
that can be used in other parts of the configuration file, such as
\fIshaper_rules\fR
option\&. The shaper itself is defined by its
\fIRate\fR, where
\fIRate\fR
stands for the maximum allowed incoming rate in
\fBbytes\fR
per second\&. When a connection exceeds this limit, ejabberd stops reading from the socket until the average rate is again below the allowed maximum\&. In the example below shaper
\fInormal\fR
limits the traffic speed to 1,000 bytes/sec and shaper
\fIfast\fR
limits the traffic speed to 50,000 bytes/sec:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
shaper:
normal: 1000
fast: 50000
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBshaper_rules\fR: \fI{ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}\fR
.RS 4
An entry allowing to declaring shaper to use for matching user/hosts\&. Semantics is similar to
\fIaccess_rules\fR
option, the only difference is that instead using
\fIallow\fR
or
\fIdeny\fR, a name of a shaper (defined in
\fIshaper\fR
option) or a positive number should be used\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
shaper_rules:
connections_limit:
10:
user: peter@example\&.com
100: admin
5: all
download_speed:
fast: admin
slow: anonymous_users
normal: all
log_days: 30
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBsm_cache_life_time\fR: \fItimeout()\fR
.RS 4
Same as
\fIcache_life_time\fR, but applied to client sessions table cache only\&. If not set, the value from
\fIcache_life_time\fR
will be used\&.
.RE
.PP
\fBsm_cache_missed\fR: \fItrue | false\fR
.RS 4
Same as
\fIcache_missed\fR, but applied to client sessions table cache only\&. If not set, the value from
\fIcache_missed\fR
will be used\&.
.RE
.PP
\fBsm_cache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as
\fIcache_size\fR, but applied to client sessions table cache only\&. If not set, the value from
\fIcache_size\fR
will be used\&.
.RE
.PP
\fBsm_db_type\fR: \fImnesia | redis | sql\fR
.RS 4
Database backend to use for client sessions information\&. The default value is picked from
\fIdefault_ram_db\fR
option, or if it\(cqs not set,
\fImnesia\fR
will be used\&.
.RE
.PP
\fBsm_use_cache\fR: \fItrue | false\fR
.RS 4
Same as
\fIuse_cache\fR, but applied to client sessions table cache only\&. If not set, the value from
\fIuse_cache\fR
will be used\&.
.RE
.PP
\fBsql_connect_timeout\fR: \fItimeout()\fR
.RS 4
A time to wait for connection to an SQL server to be established\&. The default value is
\fI5\fR
seconds\&.
.RE
.PP
\fBsql_database\fR: \fIDatabase\fR
.RS 4
An SQL database name\&. For SQLite this must be a full path to a database file\&. The default value is
\fIejabberd\fR\&.
.RE
.PP
\fBsql_keepalive_interval\fR: \fItimeout()\fR
.RS 4
An interval to make a dummy SQL request to keep alive the connections to the database\&. There is no default value, so no keepalive requests are made\&.
.RE
.sp
\fINote\fR about the next option: added in 20\&.12:
.PP
\fBsql_odbc_driver\fR: \fIPath\fR
.RS 4
Path to the ODBC driver to use to connect to a Microsoft SQL Server database\&. This option is only valid if the
\fIsql_type\fR
option is set to
\fImssql\fR\&. The default value is:
\fIlibtdsodbc\&.so\fR
.RE
.PP
\fBsql_password\fR: \fIPassword\fR
.RS 4
The password for SQL authentication\&. The default is empty string\&.
.RE
.PP
\fBsql_pool_size\fR: \fISize\fR
.RS 4
Number of connections to the SQL server that ejabberd will open for each virtual host\&. The default value is 10\&. WARNING: for SQLite this value is
\fI1\fR
by default and it\(cqs not recommended to change it due to potential race conditions\&.
.RE
.PP
\fBsql_port\fR: \fI1\&.\&.65535\fR
.RS 4
The port where the SQL server is accepting connections\&. The default is
\fI3306\fR
for MySQL,
\fI5432\fR
for PostgreSQL and
\fI1433\fR
for MS SQL\&. The option has no effect for SQLite\&.
.RE
.sp
\fINote\fR about the next option: added in 20\&.01:
.PP
\fBsql_prepared_statements\fR: \fItrue | false\fR
.RS 4
This option is
\fItrue\fR
by default, and is useful to disable prepared statements\&. The option is valid for PostgreSQL\&.
.RE
.PP
\fBsql_query_timeout\fR: \fItimeout()\fR
.RS 4
A time to wait for an SQL query response\&. The default value is
\fI60\fR
seconds\&.
.RE
.PP
\fBsql_queue_type\fR: \fIram | file\fR
.RS 4
The type of a request queue for the SQL server\&. See description of
\fIqueue_type\fR
option for the explanation\&. The default value is the value defined in
\fIqueue_type\fR
or
\fIram\fR
if the latter is not set\&.
.RE
.PP
\fBsql_server\fR: \fIHost\fR
.RS 4
A hostname or an IP address of the SQL server\&. The default value is
\fIlocalhost\fR\&.
.RE
.sp
\fINote\fR about the next option: improved in 20\&.03:
.PP
\fBsql_ssl\fR: \fItrue | false\fR
.RS 4
Whether to use SSL encrypted connections to the SQL server\&. The option is only available for MySQL and PostgreSQL\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBsql_ssl_cafile\fR: \fIPath\fR
.RS 4
A path to a file with CA root certificates that will be used to verify SQL connections\&. Implies
\fIsql_ssl\fR
and
\fIsql_ssl_verify\fR
options are set to
\fItrue\fR\&. There is no default which means certificate verification is disabled\&.
.RE
.PP
\fBsql_ssl_certfile\fR: \fIPath\fR
.RS 4
A path to a certificate file that will be used for SSL connections to the SQL server\&. Implies
\fIsql_ssl\fR
option is set to
\fItrue\fR\&. There is no default which means ejabberd won\(cqt provide a client certificate to the SQL server\&.
.RE
.PP
\fBsql_ssl_verify\fR: \fItrue | false\fR
.RS 4
Whether to verify SSL connection to the SQL server against CA root certificates defined in
\fIsql_ssl_cafile\fR
option\&. Implies
\fIsql_ssl\fR
option is set to
\fItrue\fR\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBsql_start_interval\fR: \fItimeout()\fR
.RS 4
A time to wait before retrying to restore failed SQL connection\&. The default value is
\fI30\fR
seconds\&.
.RE
.PP
\fBsql_type\fR: \fImssql | mysql | odbc | pgsql | sqlite\fR
.RS 4
The type of an SQL connection\&. The default is
\fIodbc\fR\&.
.RE
.PP
\fBsql_username\fR: \fIUsername\fR
.RS 4
A user name for SQL authentication\&. The default value is
\fIejabberd\fR\&.
.RE
.PP
\fBtrusted_proxies\fR: \fIall | [Network1, Network2, \&.\&.\&.]\fR
.RS 4
Specify what proxies are trusted when an HTTP request contains the header
\fIX\-Forwarded\-For\fR\&. You can specify
\fIall\fR
to allow all proxies, or specify a list of IPs, possibly with masks\&. The default value is an empty list\&. This allows, if enabled, to be able to know the real IP of the request, for admin purpose, or security configuration (for example using
\fImod_fail2ban\fR)\&. IMPORTANT: The proxy MUST be configured to set the
\fIX\-Forwarded\-For\fR
header if you enable this option as, otherwise, the client can set it itself and as a result the IP value cannot be trusted for security rules in ejabberd\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS 4
Enable or disable cache\&. The default is
\fItrue\fR\&. Several modules have a similar option; and some core ejabberd parts support similar options too, see
\fIauth_use_cache\fR,
\fIoauth_use_cache\fR,
\fIrouter_use_cache\fR, and
\fIsm_use_cache\fR\&.
.RE
.PP
\fBvalidate_stream\fR: \fItrue | false\fR
.RS 4
Whether to validate any incoming XML packet according to the schemas of
supported XMPP extensions\&. WARNING: the validation is only intended for the use by client developers \- don\(cqt enable it in production environment\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBversion\fR: \fIstring()\fR
.RS 4
The option can be used to set custom ejabberd version, that will be used by different parts of ejabberd, for example by
\fImod_version\fR
module\&. The default value is obtained at compile time from the underlying version control system\&.
.RE
.PP
\fBwebsocket_origin\fR: \fIignore | URL\fR
.RS 4
This option enables validation for
\fIOrigin\fR
header to protect against connections from other domains than given in the configuration file\&. In this way, the lower layer load balancer can be chosen for a specific ejabberd implementation while still providing a secure WebSocket connection\&. The default value is
\fIignore\fR\&. An example value of the
\fIURL\fR
is "https://test\&.example\&.org:8081"\&.
.RE
.PP
\fBwebsocket_ping_interval\fR: \fItimeout()\fR
.RS 4
Defines time between pings sent by the server to a client (WebSocket level protocol pings are used for this) to keep a connection active\&. If the client doesn\(cqt respond to two consecutive pings, the connection will be assumed as closed\&. The value of
\fI0\fR
can be used to disable the feature\&. This option makes the server sending pings only for connections using the RFC compliant protocol\&. For older style connections the server expects that whitespace pings would be used for this purpose\&. The default value is
\fI60\fR
seconds\&.
.RE
.PP
\fBwebsocket_timeout\fR: \fItimeout()\fR
.RS 4
Amount of time without any communication after which the connection would be closed\&. The default value is
\fI300\fR
seconds\&.
.RE
.SH "MODULES"
.sp
This section describes options of all ejabberd modules\&.
.SS "mod_adhoc"
.sp
This module implements XEP\-0050: Ad\-Hoc Commands\&. It\(cqs an auxiliary module and is only needed by some of the other modules\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBreport_commands_node\fR: \fItrue | false\fR
.RS 4
Provide the Commands item in the Service Discovery\&. Default value:
\fIfalse\fR\&.
.RE
.RE
.SS "mod_admin_extra"
.sp
This module provides additional administrative commands\&.
.sp
Details for some commands:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIban\-acount\fR: This command kicks all the connected sessions of the account from the server\&. It also changes their password to a randomly generated one, so they can\(cqt login anymore unless a server administrator changes their password again\&. It is possible to define the reason of the ban\&. The new password also includes the reason and the date and time of the ban\&. See an example below\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIpushroster\fR: (and
\fIpushroster\-all\fR) The roster file must be placed, if using Windows, on the directory where you installed ejabberd: C:/Program Files/ejabberd or similar\&. If you use other Operating System, place the file on the same directory where the \&.beam files are installed\&. See below an example roster file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIsrg\-create\fR: If you want to put a group Name with blankspaces, use the characters "\*(Aq and \*(Aq" to define when the Name starts and ends\&. See an example below\&.
.RE
.sp
The module has no options\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExamples:\fR
.RS 4
.sp
With this configuration, vCards can only be modified with mod_admin_extra commands:
.sp
.if n \{\
.RS 4
.\}
.nf
acl:
adminextraresource:
\- resource: "modadminextraf8x,31ad"
access_rules:
vcard_set:
\- allow: adminextraresource
modules:
mod_admin_extra: {}
mod_vcard:
access_set: vcard_set
.fi
.if n \{\
.RE
.\}
.sp
Content of roster file for \fIpushroster\fR command:
.sp
.if n \{\
.RS 4
.\}
.nf
[{<<"bob">>, <<"example\&.org">>, <<"workers">>, <<"Bob">>},
{<<"mart">>, <<"example\&.org">>, <<"workers">>, <<"Mart">>},
{<<"Rich">>, <<"example\&.org">>, <<"bosses">>, <<"Rich">>}]\&.
.fi
.if n \{\
.RE
.\}
.sp
With this call, the sessions of the local account which JID is boby@example\&.org will be kicked, and its password will be set to something like \fIBANNED_ACCOUNT\(em20080425T21:45:07\(em2176635\(emSpammed_rooms\fR
.sp
.if n \{\
.RS 4
.\}
.nf
ejabberdctl vhost example\&.org ban\-account boby "Spammed rooms"
.fi
.if n \{\
.RE
.\}
.sp
Call to srg\-create using double\-quotes and single\-quotes:
.sp
.if n \{\
.RS 4
.\}
.nf
ejabberdctl srg\-create g1 example\&.org "\*(AqGroup number 1\*(Aq" this_is_g1 g1
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_admin_update_sql"
.sp
This module can be used to update existing SQL database from the default to the new schema\&. Check the section Default and New Schemas for details\&. Please note that only PostgreSQL is supported\&. When the module is loaded use \fIupdate_sql\fR API\&.
.sp
The module has no options\&.
.SS "mod_announce"
.sp
This module enables configured users to broadcast announcements and to set the message of the day (MOTD)\&. Configured users can perform these actions with an XMPP client either using Ad\-hoc Commands or sending messages to specific JIDs\&.
.sp
Note that this module can be resource intensive on large deployments as it may broadcast a lot of messages\&. This module should be disabled for instances of ejabberd with hundreds of thousands users\&.
.sp
The Ad\-hoc Commands are listed in the Server Discovery\&. For this feature to work, \fImod_adhoc\fR must be enabled\&.
.sp
The specific JIDs where messages can be sent are listed below\&. The first JID in each entry will apply only to the specified virtual host example\&.org, while the JID between brackets will apply to all virtual hosts in ejabberd:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example\&.org/announce/all (example\&.org/announce/all\-hosts/all):: The message is sent to all registered users\&. If the user is online and connected to several resources, only the resource with the highest priority will receive the message\&. If the registered user is not connected, the message will be stored offline in assumption that offline storage (see
\fImod_offline\fR) is enabled\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example\&.org/announce/online (example\&.org/announce/all\-hosts/online):: The message is sent to all connected users\&. If the user is online and connected to several resources, all resources will receive the message\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example\&.org/announce/motd (example\&.org/announce/all\-hosts/motd):: The message is set as the message of the day (MOTD) and is sent to users when they login\&. In addition the message is sent to all connected users (similar to announce/online)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example\&.org/announce/motd/update (example\&.org/announce/all\-hosts/motd/update):: The message is set as message of the day (MOTD) and is sent to users when they login\&. The message is not sent to any currently connected user\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example\&.org/announce/motd/delete (example\&.org/announce/all\-hosts/motd/delete):: Any message sent to this JID removes the existing message of the day (MOTD)\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
This option specifies who is allowed to send announcements and to set the message of the day\&. The default value is
\fInone\fR
(i\&.e\&. nobody is able to send such messages)\&.
.RE
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS 4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.SS "mod_avatar"
.sp
The purpose of the module is to cope with legacy and modern XMPP clients posting avatars\&. The process is described in XEP\-0398: User Avatar to vCard\-Based Avatars Conversion\&.
.sp
Also, the module supports conversion between avatar image formats on the fly\&.
.sp
The module depends on \fImod_vcard\fR, \fImod_vcard_xupdate\fR and \fImod_pubsub\fR\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBconvert\fR: \fI{From: To}\fR
.RS 4
Defines image conversion rules: the format in
\fIFrom\fR
will be converted to format in
\fITo\fR\&. The value of
\fIFrom\fR
can also be
\fIdefault\fR, which is match\-all rule\&. NOTE: the list of supported formats is detected at compile time depending on the image libraries installed in the system\&.
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
convert:
webp: jpg
default: png
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBrate_limit\fR: \fINumber\fR
.RS 4
Limit any given JID by the number of avatars it is able to convert per minute\&. This is to protect the server from image conversion DoS\&. The default value is
\fI10\fR\&.
.RE
.RE
.SS "mod_block_strangers"
.sp
This module allows to block/log messages coming from an unknown entity\&. If a writing entity is not in your roster, you can let this module drop and/or log the message\&. By default you\(cqll just not receive message from that entity\&. Enable this module if you want to drop SPAM messages\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
The option is supposed to be used when
\fIallow_local_users\fR
and
\fIallow_transports\fR
are not enough\&. It\(cqs an ACL where
\fIdeny\fR
means the message will be rejected (or a CAPTCHA would be generated for a presence, if configured), and
\fIallow\fR
means the sender is whitelisted and the stanza will pass through\&. The default value is
\fInone\fR, which means nothing is whitelisted\&.
.RE
.PP
\fBallow_local_users\fR: \fItrue | false\fR
.RS 4
This option specifies if strangers from the same local host should be accepted or not\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBallow_transports\fR: \fItrue | false\fR
.RS 4
If set to
\fItrue\fR
and some server\(cqs JID is in user\(cqs roster, then messages from any user of this server are accepted even if no subscription present\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBcaptcha\fR: \fItrue | false\fR
.RS 4
Whether to generate CAPTCHA or not in response to messages from strangers\&. See also section
CAPTCHA
of the Configuration Guide\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBdrop\fR: \fItrue | false\fR
.RS 4
This option specifies if strangers messages should be dropped or not\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBlog\fR: \fItrue | false\fR
.RS 4
This option specifies if strangers\*(Aq messages should be logged (as info message) in ejabberd\&.log\&. The default value is
\fIfalse\fR\&.
.RE
.RE
.SS "mod_blocking"
.sp
The module implements XEP\-0191: Blocking Command\&.
.sp
This module depends on \fImod_privacy\fR where all the configuration is performed\&.
.sp
The module has no options\&.
.SS "mod_bosh"
.sp
This module implements XMPP over BOSH as defined in XEP\-0124 and XEP\-0206\&. BOSH stands for Bidirectional\-streams Over Synchronous HTTP\&. It makes it possible to simulate long lived connections required by XMPP over the HTTP protocol\&. In practice, this module makes it possible to use XMPP in a browser without WebSocket support and more generally to have a way to use XMPP while having to get through an HTTP proxy\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBjson\fR: \fItrue | false\fR
.RS 4
This option has no effect\&.
.RE
.PP
\fBmax_concat\fR: \fIpos_integer() | infinity\fR
.RS 4
This option limits the number of stanzas that the server will send in a single bosh request\&. The default value is
\fIunlimited\fR\&.
.RE
.PP
\fBmax_inactivity\fR: \fItimeout()\fR
.RS 4
The option defines the maximum inactivity period\&. The default value is
\fI30\fR
seconds\&.
.RE
.PP
\fBmax_pause\fR: \fIpos_integer()\fR
.RS 4
Indicate the maximum length of a temporary session pause (in seconds) that a client can request\&. The default value is
\fI120\fR\&.
.RE
.PP
\fBprebind\fR: \fItrue | false\fR
.RS 4
If enabled, the client can create the session without going through authentication\&. Basically, it creates a new session with anonymous authentication\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBqueue_type\fR: \fIram | file\fR
.RS 4
Same as top\-level
\fIqueue_type\fR
option, but applied to this module only\&.
.RE
.PP
\fBram_db_type\fR: \fImnesia | sql | redis\fR
.RS 4
Same as top\-level
\fIdefault_ram_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExample:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\-
port: 5222
module: ejabberd_c2s
\-
port: 5443
module: ejabberd_http
request_handlers:
/bosh: mod_bosh
modules:
mod_bosh: {}
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_caps"
.sp
This module implements XEP\-0115: Entity Capabilities\&. The main purpose of the module is to provide PEP functionality (see \fImod_pubsub\fR)\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS 4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.SS "mod_carboncopy"
.sp
The module implements XEP\-0280: Message Carbons\&. The module broadcasts messages on all connected user resources (devices)\&.
.sp
The module has no options\&.
.SS "mod_client_state"
.sp
This module allows for queueing certain types of stanzas when a client indicates that the user is not actively using the client right now (see XEP\-0352: Client State Indication)\&. This can save bandwidth and resources\&.
.sp
A stanza is dropped from the queue if it\(cqs effectively obsoleted by a new one (e\&.g\&., a new presence stanza would replace an old one from the same client)\&. The queue is flushed if a stanza arrives that won\(cqt be queued, or if the queue size reaches a certain limit (currently 100 stanzas), or if the client becomes active again\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBqueue_chat_states\fR: \fItrue | false\fR
.RS 4
Queue "standalone" chat state notifications (as defined in
XEP\-0085: Chat State Notifications) while a client indicates inactivity\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBqueue_pep\fR: \fItrue | false\fR
.RS 4
Queue PEP notifications while a client is inactive\&. When the queue is flushed, only the most recent notification of a given PEP node is delivered\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBqueue_presence\fR: \fItrue | false\fR
.RS 4
While a client is inactive, queue presence stanzas that indicate (un)availability\&. The default value is
\fItrue\fR\&.
.RE
.RE
.SS "mod_configure"
.sp
The module provides server configuration functionality via XEP\-0050: Ad\-Hoc Commands\&. This module requires \fImod_adhoc\fR to be loaded\&.
.sp
The module has no options\&.
.SS "mod_conversejs"
.sp
This module serves a simple page for the Converse XMPP web browser client\&.
.sp
This module is available since ejabberd 21\&.12\&. Several options were improved in ejabberd 22\&.05\&.
.sp
To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR\fIejabberd_http\fR → request_handlers\&.
.sp
Make sure either \fImod_bosh\fR or \fIejabberd_http_ws\fR request_handlers are enabled\&.
.sp
When \fIconversejs_css\fR and \fIconversejs_script\fR are \fIauto\fR, by default they point to the public Converse client\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBbosh_service_url\fR: \fIauto | BoshURL\fR
.RS 4
BOSH service URL to which Converse can connect to\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&. If set to
\fIauto\fR, it will build the URL of the first configured BOSH request handler\&. The default value is
\fIauto\fR\&.
.RE
.PP
\fBconversejs_css\fR: \fIauto | URL\fR
.RS 4
Converse CSS URL\&. The keyword
\fI@HOST@\fR
is replaced with the hostname\&. The default value is
\fIauto\fR\&.
.RE
.sp
\fINote\fR about the next option: added in 22\&.05:
.PP
\fBconversejs_options\fR: \fI{Name: Value}\fR
.RS 4
Specify additional options to be passed to Converse\&. See
Converse configuration\&. Only boolean, integer and string values are supported; lists are not supported\&.
.RE
.sp
\fINote\fR about the next option: added in 22\&.05:
.PP
\fBconversejs_resources\fR: \fIPath\fR
.RS 4
Local path to the Converse files\&. If not set, the public Converse client will be used instead\&.
.RE
.PP
\fBconversejs_script\fR: \fIauto | URL\fR
.RS 4
Converse main script URL\&. The keyword
\fI@HOST@\fR
is replaced with the hostname\&. The default value is
\fIauto\fR\&.
.RE
.PP
\fBdefault_domain\fR: \fIDomain\fR
.RS 4
Specify a domain to act as the default for user JIDs\&. The keyword
\fI@HOST@\fR
is replaced with the hostname\&. The default value is
\fI@HOST@\fR\&.
.RE
.PP
\fBwebsocket_url\fR: \fIauto | WebSocketURL\fR
.RS 4
A WebSocket URL to which Converse can connect to\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&. If set to
\fIauto\fR, it will build the URL of the first configured WebSocket request handler\&. The default value is
\fIauto\fR\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExamples:\fR
.RS 4
.sp
Manually setup WebSocket url, and use the public Converse client:
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\-
port: 5280
module: ejabberd_http
request_handlers:
/bosh: mod_bosh
/websocket: ejabberd_http_ws
/conversejs: mod_conversejs
modules:
mod_bosh: {}
mod_conversejs:
websocket_url: "ws://@HOST@:5280/websocket"
.fi
.if n \{\
.RE
.\}
.sp
Host Converse locally and let auto detection of WebSocket and Converse URLs:
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\-
port: 443
module: ejabberd_http
tls: true
request_handlers:
/websocket: ejabberd_http_ws
/conversejs: mod_conversejs
modules:
mod_conversejs:
conversejs_resources: "/home/ejabberd/conversejs\-9\&.0\&.0/package/dist"
.fi
.if n \{\
.RE
.\}
.sp
Configure some additional options for Converse
.sp
.if n \{\
.RS 4
.\}
.nf
modules:
mod_conversejs:
websocket_url: auto
conversejs_options:
auto_away: 30
clear_cache_on_logout: true
i18n: "pt"
locked_domain: "@HOST@"
message_archiving: always
theme: dracula
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_delegation"
.sp
This module is an implementation of XEP\-0355: Namespace Delegation\&. Only admin mode has been implemented by now\&. Namespace delegation allows external services to handle IQ using specific namespace\&. This may be applied for external PEP service\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
Security issue: Namespace delegation gives components access to sensitive data, so permission should be granted carefully, only if you trust the component\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
This module is complementary to \fImod_privilege\fR but can also be used separately\&.
.sp .5v
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBnamespaces\fR: \fI{Namespace: Options}\fR
.RS 4
If you want to delegate namespaces to a component, specify them in this option, and associate them to an access rule\&. The
\fIOptions\fR
are:
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
The option defines which components are allowed for namespace delegation\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBfiltering\fR: \fIAttributes\fR
.RS 4
The list of attributes\&. Currently not used\&.
.RE
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExamples:\fR
.RS 4
.sp
Make sure you do not delegate the same namespace to several services at the same time\&. As in the example provided later, to have the \fIsat\-pubsub\&.example\&.org\fR component perform correctly disable the \fImod_pubsub\fR module\&.
.sp
.if n \{\
.RS 4
.\}
.nf
access_rules:
external_pubsub:
allow: external_component
external_mam:
allow: external_component
acl:
external_component:
server: sat\-pubsub\&.example\&.org
modules:
\&.\&.\&.
mod_delegation:
namespaces:
urn:xmpp:mam:1:
access: external_mam
http://jabber\&.org/protocol/pubsub:
access: external_pubsub
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_disco"
.sp
This module adds support for XEP\-0030: Service Discovery\&. With this module enabled, services on your server can be discovered by XMPP clients\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBextra_domains\fR: \fI[Domain, \&.\&.\&.]\fR
.RS 4
With this option, you can specify a list of extra domains that are added to the Service Discovery item list\&. The default value is an empty list\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS 4
A name of the server in the Service Discovery\&. This will only be displayed by special XMPP clients\&. The default value is
\fIejabberd\fR\&.
.RE
.PP
\fBserver_info\fR: \fI[Info, \&.\&.\&.]\fR
.RS 4
Specify additional information about the server, as described in
XEP\-0157: Contact Addresses for XMPP Services\&. Every
\fIInfo\fR
element in the list is constructed from the following options:
.PP
\fBmodules\fR: \fIall | [Module, \&.\&.\&.]\fR
.RS 4
The value can be the keyword
\fIall\fR, in which case the information is reported in all the services, or a list of ejabberd modules, in which case the information is only specified for the services provided by those modules\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS 4
The field
\fIvar\fR
name that will be defined\&. See XEP\-0157 for some standardized names\&.
.RE
.PP
\fBurls\fR: \fI[URI, \&.\&.\&.]\fR
.RS 4
A list of contact URIs, such as HTTP URLs, XMPP URIs and so on\&.
.RE
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
server_info:
\-
modules: all
name: abuse\-addresses
urls: ["mailto:abuse@shakespeare\&.lit"]
\-
modules: [mod_muc]
name: "Web chatroom logs"
urls: ["http://www\&.example\&.org/muc\-logs"]
\-
modules: [mod_disco]
name: feedback\-addresses
urls:
\- http://shakespeare\&.lit/feedback\&.php
\- mailto:feedback@shakespeare\&.lit
\- xmpp:feedback@shakespeare\&.lit
\-
modules:
\- mod_disco
\- mod_vcard
name: admin\-addresses
urls:
\- mailto:xmpp@shakespeare\&.lit
\- xmpp:admins@shakespeare\&.lit
.fi
.if n \{\
.RE
.\}
.RE
.RE
.SS "mod_fail2ban"
.sp
The module bans IPs that show the malicious signs\&. Currently only C2S authentication failures are detected\&.
.sp
Unlike the standalone program, \fImod_fail2ban\fR clears the record of authentication failures after some time since the first failure or on a successful authentication\&. It also does not simply block network traffic, but provides the client with a descriptive error message\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
You should not use this module behind a proxy or load balancer\&. ejabberd will see the failures as coming from the load balancer and, when the threshold of auth failures is reached, will reject all connections coming from the load balancer\&. You can lock all your user base out of ejabberd when using this module behind a proxy\&.
.sp .5v
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
Specify an access rule for whitelisting IP addresses or networks\&. If the rule returns
\fIallow\fR
for a given IP address, that address will never be banned\&. The
\fIAccessName\fR
should be of type
\fIip\fR\&. The default value is
\fInone\fR\&.
.RE
.PP
\fBc2s_auth_ban_lifetime\fR: \fItimeout()\fR
.RS 4
The lifetime of the IP ban caused by too many C2S authentication failures\&. The default value is
\fI1\fR
hour\&.
.RE
.PP
\fBc2s_max_auth_failures\fR: \fINumber\fR
.RS 4
The number of C2S authentication failures to trigger the IP ban\&. The default value is
\fI20\fR\&.
.RE
.RE
.SS "mod_host_meta"
.sp
This module serves small \fIhost\-meta\fR files as described in XEP\-0156: Discovering Alternative XMPP Connection Methods\&.
.sp
This module is available since ejabberd 22\&.05\&.
.sp
To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR\fIejabberd_http\fR → request_handlers\&.
.sp
Notice it only works if ejabberd_http has tls enabled\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBbosh_service_url\fR: \fIundefined | auto | BoshURL\fR
.RS 4
BOSH service URL to announce\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&. If set to
\fIauto\fR, it will build the URL of the first configured BOSH request handler\&. The default value is
\fIauto\fR\&.
.RE
.PP
\fBwebsocket_url\fR: \fIundefined | auto | WebSocketURL\fR
.RS 4
WebSocket URL to announce\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&. If set to
\fIauto\fR, it will build the URL of the first configured WebSocket request handler\&. The default value is
\fIauto\fR\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExample:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\-
port: 443
module: ejabberd_http
tls: true
request_handlers:
/bosh: mod_bosh
/ws: ejabberd_http_ws
/\&.well\-known/host\-meta: mod_host_meta
/\&.well\-known/host\-meta\&.json: mod_host_meta
modules:
mod_bosh: {}
mod_host_meta:
bosh_service_url: "https://@HOST@:5443/bosh"
websocket_url: "wss://@HOST@:5443/ws"
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_http_api"
.sp
This module provides a ReST interface to call ejabberd API commands using JSON data\&.
.sp
To use this module, in addition to adding it to the \fImodules\fR section, you must also enable it in \fIlisten\fR\fIejabberd_http\fR → request_handlers\&.
.sp
To use a specific API version N, when defining the URL path in the request_handlers, add a \fIvN\fR\&. For example: \fI/api/v2: mod_http_api\fR
.sp
To run a command, send a POST request to the corresponding URL: \fIhttp://localhost:5280/api/<command_name>\fR
.sp
The module has no options\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExample:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\-
port: 5280
module: ejabberd_http
request_handlers:
/api: mod_http_api
modules:
mod_http_api: {}
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_http_fileserver"
.sp
This simple module serves files from the local disk over HTTP\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccesslog\fR: \fIPath\fR
.RS 4
File to log accesses using an Apache\-like format\&. No log will be recorded if this option is not specified\&.
.RE
.PP
\fBcontent_types\fR: \fI{Extension: Type}\fR
.RS 4
Specify mappings of extension to content type\&. There are several content types already defined\&. With this option you can add new definitions or modify existing ones\&. The default values are:
.sp
\fBExample\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
content_types:
\&.css: text/css
\&.gif: image/gif
\&.html: text/html
\&.jar: application/java\-archive
\&.jpeg: image/jpeg
\&.jpg: image/jpeg
\&.js: text/javascript
\&.png: image/png
\&.svg: image/svg+xml
\&.txt: text/plain
\&.xml: application/xml
\&.xpi: application/x\-xpinstall
\&.xul: application/vnd\&.mozilla\&.xul+xml
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBcustom_headers\fR: \fI{Name: Value}\fR
.RS 4
Indicate custom HTTP headers to be included in all responses\&. There are no custom headers by default\&.
.RE
.PP
\fBdefault_content_type\fR: \fIType\fR
.RS 4
Specify the content type to use for unknown extensions\&. The default value is
\fIapplication/octet\-stream\fR\&.
.RE
.PP
\fBdirectory_indices\fR: \fI[Index, \&.\&.\&.]\fR
.RS 4
Indicate one or more directory index files, similarly to Apache\(cqs
\fIDirectoryIndex\fR
variable\&. When an HTTP request hits a directory instead of a regular file, those directory indices are looked in order, and the first one found is returned\&. The default value is an empty list\&.
.RE
.PP
\fBdocroot\fR: \fIPath\fR
.RS 4
Directory to serve the files from\&. This is a mandatory option\&.
.RE
.PP
\fBmust_authenticate_with\fR: \fI[{Username, Hostname}, \&.\&.\&.]\fR
.RS 4
List of accounts that are allowed to use this service\&. Default value:
\fI[]\fR\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExamples:\fR
.RS 4
.sp
This example configuration will serve the files from the local directory \fI/var/www\fR in the address \fIhttp://example\&.org:5280/pub/archive/\fR\&. In this example a new content type \fIogg\fR is defined, \fIpng\fR is redefined, and \fIjpg\fR definition is deleted:
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\&.\&.\&.
\-
port: 5280
module: ejabberd_http
request_handlers:
\&.\&.\&.
/pub/archive: mod_http_fileserver
\&.\&.\&.
\&.\&.\&.
modules:
\&.\&.\&.
mod_http_fileserver:
docroot: /var/www
accesslog: /var/log/ejabberd/access\&.log
directory_indices:
\- index\&.html
\- main\&.htm
custom_headers:
X\-Powered\-By: Erlang/OTP
X\-Fry: "It\*(Aqs a widely\-believed fact!"
content_types:
\&.ogg: audio/ogg
\&.png: image/png
default_content_type: text/html
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_http_upload"
.sp
This module allows for requesting permissions to upload a file via HTTP as described in XEP\-0363: HTTP File Upload\&. If the request is accepted, the client receives a URL for uploading the file and another URL from which that file can later be downloaded\&.
.sp
In order to use this module, it must be enabled in \fIlisten\fR\fIejabberd_http\fR → request_handlers\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
This option defines the access rule to limit who is permitted to use the HTTP upload service\&. The default value is
\fIlocal\fR\&. If no access rule of that name exists, no user will be allowed to use the service\&.
.RE
.PP
\fBcustom_headers\fR: \fI{Name: Value}\fR
.RS 4
This option specifies additional header fields to be included in all HTTP responses\&. By default no custom headers are included\&.
.RE
.PP
\fBdir_mode\fR: \fIPermission\fR
.RS 4
This option defines the permission bits of the
\fIdocroot\fR
directory and any directories created during file uploads\&. The bits are specified as an octal number (see the chmod(1) manual page) within double quotes\&. For example: "0755"\&. The default is undefined, which means no explicit permissions will be set\&.
.RE
.PP
\fBdocroot\fR: \fIPath\fR
.RS 4
Uploaded files are stored below the directory specified (as an absolute path) with this option\&. The keyword @HOME@ is replaced with the home directory of the user running ejabberd, and the keyword @HOST@ with the virtual host name\&. The default value is "@HOME@/upload"\&.
.RE
.PP
\fBexternal_secret\fR: \fIText\fR
.RS 4
This option makes it possible to offload all HTTP Upload processing to a separate HTTP server\&. Both ejabberd and the HTTP server should share this secret and behave exactly as described at
Prosody\(cqs mod_http_upload_external
in the
\fIImplementation\fR
section\&. There is no default value\&.
.RE
.PP
\fBfile_mode\fR: \fIPermission\fR
.RS 4
This option defines the permission bits of uploaded files\&. The bits are specified as an octal number (see the chmod(1) manual page) within double quotes\&. For example: "0644"\&. The default is undefined, which means no explicit permissions will be set\&.
.RE
.PP
\fBget_url\fR: \fIURL\fR
.RS 4
This option specifies the initial part of the GET URLs used for downloading the files\&. The default value is
\fIundefined\fR\&. When this option is
\fIundefined\fR, this option is set to the same value as
\fIput_url\fR\&. The keyword @HOST@ is replaced with the virtual host name\&. NOTE: if GET requests are handled by
\fImod_http_upload\fR, the
\fIget_url\fR
must match the
\fIput_url\fR\&. Setting it to a different value only makes sense if an external web server or
\fImod_http_fileserver\fR
is used to serve the uploaded files\&.
.RE
.PP
\fBhost\fR
.RS 4
Deprecated\&. Use
\fIhosts\fR
instead\&.
.RE
.PP
\fBhosts\fR: \fI[Host, \&.\&.\&.]\fR
.RS 4
This option defines the Jabber IDs of the service\&. If the
\fIhosts\fR
option is not specified, the only Jabber ID will be the hostname of the virtual host with the prefix "upload\&."\&. The keyword
\fI@HOST@\fR
is replaced with the real virtual host name\&.
.RE
.PP
\fBjid_in_url\fR: \fInode | sha1\fR
.RS 4
When this option is set to
\fInode\fR, the node identifier of the user\(cqs JID (i\&.e\&., the user name) is included in the GET and PUT URLs generated by
\fImod_http_upload\fR\&. Otherwise, a SHA\-1 hash of the user\(cqs bare JID is included instead\&. The default value is
\fIsha1\fR\&.
.RE
.PP
\fBmax_size\fR: \fISize\fR
.RS 4
This option limits the acceptable file size\&. Either a number of bytes (larger than zero) or
\fIinfinity\fR
must be specified\&. The default value is
\fI104857600\fR\&.
.RE
.PP
\fBname\fR: \fIName\fR
.RS 4
A name of the service in the Service Discovery\&. This will only be displayed by special XMPP clients\&. The default value is "HTTP File Upload"\&.
.RE
.PP
\fBput_url\fR: \fIURL\fR
.RS 4
This option specifies the initial part of the PUT URLs used for file uploads\&. The keyword @HOST@ is replaced with the virtual host name\&. NOTE: different virtual hosts cannot use the same PUT URL\&. The default value is "https://@HOST@:5443/upload"\&.
.RE
.PP
\fBrm_on_unregister\fR: \fItrue | false\fR
.RS 4
This option specifies whether files uploaded by a user should be removed when that user is unregistered\&. The default value is
\fItrue\fR\&.
.RE
.PP
\fBsecret_length\fR: \fILength\fR
.RS 4
This option defines the length of the random string included in the GET and PUT URLs generated by
\fImod_http_upload\fR\&. The minimum length is 8 characters, but it is recommended to choose a larger value\&. The default value is
\fI40\fR\&.
.RE
.PP
\fBservice_url\fR
.RS 4
Deprecated\&.
.RE
.PP
\fBthumbnail\fR: \fItrue | false\fR
.RS 4
This option specifies whether ejabberd should create thumbnails of uploaded images\&. If a thumbnail is created, a <thumbnail/> element that contains the download <uri/> and some metadata is returned with the PUT response\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBvcard\fR: \fIvCard\fR
.RS 4
A custom vCard of the service that will be displayed by some XMPP clients in Service Discovery\&. The value of
\fIvCard\fR
is a YAML map constructed from an XML representation of vCard\&. Since the representation has no attributes, the mapping is straightforward\&.
.sp
For example, the following XML representation of vCard:
.sp
.if n \{\
.RS 4
.\}
.nf
<vCard xmlns=\*(Aqvcard\-temp\*(Aq>
<FN>Conferences</FN>
<ADR>
<WORK/>
<STREET>Elm Street</STREET>
</ADR>
</vCard>
.fi
.if n \{\
.RE
.\}
.sp
will be translated to:
.sp
.if n \{\
.RS 4
.\}
.nf
vcard:
fn: Conferences
adr:
\-
work: true
street: Elm Street
.fi
.if n \{\
.RE
.\}
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExample:\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
listen:
\&.\&.\&.
\-
port: 5443
module: ejabberd_http
tls: true
request_handlers:
\&.\&.\&.
/upload: mod_http_upload
\&.\&.\&.
\&.\&.\&.
modules:
\&.\&.\&.
mod_http_upload:
docroot: /ejabberd/upload
put_url: "https://@HOST@:5443/upload"
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_http_upload_quota"
.sp
This module adds quota support for mod_http_upload\&.
.sp
This module depends on \fImod_http_upload\fR\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess_hard_quota\fR: \fIAccessName\fR
.RS 4
This option defines which access rule is used to specify the "hard quota" for the matching JIDs\&. That rule must yield a positive number for any JID that is supposed to have a quota limit\&. This is the number of megabytes a corresponding user may upload\&. When this threshold is exceeded, ejabberd deletes the oldest files uploaded by that user until their disk usage equals or falls below the specified soft quota (see
\fIaccess_soft_quota\fR)\&. The default value is
\fIhard_upload_quota\fR\&.
.RE
.PP
\fBaccess_soft_quota\fR: \fIAccessName\fR
.RS 4
This option defines which access rule is used to specify the "soft quota" for the matching JIDs\&. That rule must yield a positive number of megabytes for any JID that is supposed to have a quota limit\&. See the description of the
\fIaccess_hard_quota\fR
option for details\&. The default value is
\fIsoft_upload_quota\fR\&.
.RE
.PP
\fBmax_days\fR: \fIDays\fR
.RS 4
If a number larger than zero is specified, any files (and directories) older than this number of days are removed from the subdirectories of the
\fIdocroot\fR
directory, once per day\&. The default value is
\fIinfinity\fR\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBExamples:\fR
.RS 4
.sp
Please note that it\(cqs not necessary to specify the \fIaccess_hard_quota\fR and \fIaccess_soft_quota\fR options in order to use the quota feature\&. You can stick to the default names and just specify access rules such as those in this example:
.sp
.if n \{\
.RS 4
.\}
.nf
shaper_rules:
\&.\&.\&.
soft_upload_quota:
1000: all # MiB
hard_upload_quota:
1100: all # MiB
\&.\&.\&.
modules:
\&.\&.\&.
mod_http_upload: {}
mod_http_upload_quota:
max_days: 100
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.RE
.SS "mod_jidprep"
.sp
This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format\&. This might be useful for clients in certain constrained environments, or for testing purposes\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess\fR: \fIAccessName\fR
.RS 4
This option defines which access rule will be used to control who is allowed to use this service\&. The default value is
\fIlocal\fR\&.
.RE
.RE
.SS "mod_last"
.sp
This module adds support for XEP\-0012: Last Activity\&. It can be used to discover when a disconnected user last accessed the server, to know when a connected user was last active on the server, or to query the uptime of the ejabberd server\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
Same as top\-level
\fIcache_life_time\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_missed\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIcache_missed\fR
option, but applied to this module only\&.
.RE
.PP
\fBcache_size\fR: \fIpos_integer() | infinity\fR
.RS 4
Same as top\-level
\fIcache_size\fR
option, but applied to this module only\&.
.RE
.PP
\fBdb_type\fR: \fImnesia | sql\fR
.RS 4
Same as top\-level
\fIdefault_db\fR
option, but applied to this module only\&.
.RE
.PP
\fBuse_cache\fR: \fItrue | false\fR
.RS 4
Same as top\-level
\fIuse_cache\fR
option, but applied to this module only\&.
.RE
.RE
.SS "mod_legacy_auth"
.sp
The module implements XEP\-0078: Non\-SASL Authentication\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
This type of authentication was obsoleted in 2008 and you unlikely need this module unless you have something like outdated Jabber bots\&.
.sp .5v
.RE
.sp
The module has no options\&.
.SS "mod_mam"
.sp
This module implements XEP\-0313: Message Archive Management\&. Compatible XMPP clients can use it to store their chat history on the server\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAvailable options:\fR
.RS 4
.PP
\fBaccess_preferences\fR: \fIAccessName\fR
.RS 4
This access rule defines who is allowed to modify the MAM preferences\&. The default value is
\fIall\fR\&.
.RE
.PP
\fBassume_mam_usage\fR: \fItrue | false\fR
.RS 4
This option determines how ejabberd\(cqs stream management code (see
\fImod_stream_mgmt\fR) handles unacknowledged messages when the connection is lost\&. Usually, such messages are either bounced or resent\&. However, neither is done for messages that were stored in the user\(cqs MAM archive if this option is set to
\fItrue\fR\&. In this case, ejabberd assumes those messages will be retrieved from the archive\&. The default value is
\fIfalse\fR\&.
.RE
.PP
\fBcache_life_time\fR: \fItimeout()\fR
.RS 4
Same as top\-level
\fIcache_life_time\fR