xmpp.chapril.org-ejabberd/man/ejabberd.yml.5

'\" t
.\"     Title: ejabberd.yml
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/08/2020
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "EJABBERD\&.YML" "5" "01/08/2020" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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 splitted into 3 main categories: \fIModules\fR, \fIListeners\fR and everything else called \fITop Level\fR options\&. Thus this document is splitted 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/19\&.09/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
The option specifies 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\&. ACME is used 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
\fIlogin_anon\fR
means that the anonymous login method will be used\&.
\fIsasl_anon\fR
means that the SASL Anonymous method will be used\&.
\fIboth\fR
means that SASL Anonymous and login anonymous are both enabled\&. The default value is
\fIsasl_anon\fR\&.
.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_password_format\fR: \fIplain | scram\fR
.RS 4
The option defines in what format the users passwords are stored\&.
\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\&.
\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\&.
.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 subjectAltName field\&. There is no default value\&.
.RE
.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
.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
\fIone hour\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\&.
.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\&.
.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
.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 sofisticated 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 | sql | redis\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
\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
\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\&.
.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=Jabber 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
Listeners
section of this document 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\&.
.RE
.PP
\fBlog_rotate_size\fR: \fISize\fR
.RS 4
The size (in bytes) of a log file to trigger rotation\&. The default value is
\fI10485760\fR
(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 of this document 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\fR
minute\&.
.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/19\&.09/sql\&. There are two schemas available\&. The default lecacy 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
.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_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
.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 | sql | redis\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
The access rule to restrict server\-to\-server connections\&. The default value is
\fIall\fR
which means no restrictions are applied\&.
.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
\fIca_file\fR
will be used\&.
.RE
.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