Chapril/xmpp.chapril.org-ejabberd
25
1
Fork 0
mirror of https://github.com/processone/ejabberd.git synced 2024-11-20 16:15:59 +01:00
Code Releases Activity
f56739fd9f
xmpp.chapril.org-ejabberd/src/ejabberd_options_doc.erl

1488 lines
72 KiB
Erlang
Raw Normal View History

Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
%%%----------------------------------------------------------------------
Update copyright year to 2024 (#4139)
2024-01-22 16:40:01 +01:00
%%% ejabberd, Copyright (C) 2002-2024 ProcessOne
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
%%%
%%% This program is free software; you can redistribute it and/or
%%% modify it under the terms of the GNU General Public License as
%%% published by the Free Software Foundation; either version 2 of the
%%% License, or (at your option) any later version.
%%%
%%% This program is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
%%% General Public License for more details.
%%%
%%% You should have received a copy of the GNU General Public License along
%%% with this program; if not, write to the Free Software Foundation, Inc.,
%%% 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
%%%
%%%----------------------------------------------------------------------
-module(ejabberd_options_doc).
%% API
-export([doc/0]).
-include("translate.hrl").
%%%===================================================================
%%% API
%%%===================================================================
doc() ->
[{hosts,
#{value => ?T("[Domain1, Domain2, ...]"),
desc =>
?T("The option defines a list containing one or more "
"domains that 'ejabberd' will serve. This is a "
"**mandatory** option.")}},
{listen,
#{value => "[Options, ...]",
desc =>
Minor fixes in doc
2020-04-09 12:01:05 +02:00
?T("The option for listeners configuration. See the "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"_`listen.md|Listen Modules`_ section "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"for details.")}},
{modules,
#{value => "{Module: Options}",
desc =>
?T("The option for modules configuration. See "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"_`modules.md|Modules`_ section "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"for details.")}},
{loglevel,
#{value =>
"none | emergency | alert | critical | "
"error | warning | notice | info | debug",
desc =>
?T("Verbosity of log files generated by ejabberd. "
"The default value is 'info'. "
"NOTE: previous versions of ejabberd had log levels "
"defined in numeric format ('0..5'). The numeric values "
"are still accepted for backward compatibility, but "
"are not recommended.")}},
{cache_life_time,
#{value => "timeout()",
desc =>
?T("The time of a cached item to keep in cache. "
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
"Once it's expired, the corresponding item is "
Update documentation to match the implemented options values (#3675)
2021-09-14 11:24:49 +02:00
"erased from cache. The default value is '1 hour'. "
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
"Several modules have a similar option; and some core "
"ejabberd parts support similar options too, see "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`auth_cache_life_time`_, _`oauth_cache_life_time`_, "
"_`router_cache_life_time`_, and _`sm_cache_life_time`_.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{cache_missed,
#{value => "true | false",
desc =>
?T("Whether or not to cache missed lookups. When there is "
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
"an attempt to lookup for a value in a database and "
"this value is not found and the option is set to 'true', "
"this attempt will be cached and no attempts will be "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"performed until the cache expires (see _`cache_life_time`_). "
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
"Usually you don't want to change it. Default is 'true'. "
"Several modules have a similar option; and some core "
"ejabberd parts support similar options too, see "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`auth_cache_missed`_, _`oauth_cache_missed`_, "
"_`router_cache_missed`_, and _`sm_cache_missed`_.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{cache_size,
#{value => "pos_integer() | infinity",
desc =>
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
?T("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's 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 '1000'. "
"Several modules have a similar option; and some core "
"ejabberd parts support similar options too, see "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`auth_cache_size`_, _`oauth_cache_size`_, "
"_`router_cache_size`_, and _`sm_cache_size`_.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{use_cache,
#{value => "true | false",
Copy more option explanations from ejabberd Docs site
2020-04-08 18:49:41 +02:00
desc =>
?T("Enable or disable cache. The default is 'true'. "
"Several modules have a similar option; and some core "
"ejabberd parts support similar options too, see "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`auth_use_cache`_, _`oauth_use_cache`_, _`router_use_cache`_, "
"and _`sm_use_cache`_.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{default_db,
#{value => "mnesia | sql",
desc =>
?T("Default persistent storage for ejabberd. "
"Modules and other components (e.g. authentication) "
"may have its own value. The default value is 'mnesia'.")}},
{default_ram_db,
Sort databases alphabetically in options doc (thanks to Neustradamus)(#3246)
2020-05-19 13:11:18 +02:00
#{value => "mnesia | redis | sql",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("Default volatile (in-memory) storage for ejabberd. "
"Modules and other components (e.g. session management) "
"may have its own value. The default value is 'mnesia'.")}},
{queue_type,
#{value => "ram | file",
desc =>
?T("Default type of queues in ejabberd. "
"Modules may have its own value of the option. "
"The value of 'ram' means that queues will be kept in memory. "
"If value 'file' is set, you may also specify directory "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"in _`queue_dir`_ option where file queues will be placed. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"The default value is 'ram'.")}},
{version,
#{value => "string()",
desc =>
?T("The option can be used to set custom ejabberd version, "
"that will be used by different parts of ejabberd, for "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"example by _`mod_version`_ module. The default value is "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"obtained at compile time from the underlying version "
"control system.")}},
{acl,
#{value => "{ACLName: {ACLType: ACLValue}}",
desc =>
?T("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 'ACLName': it can be any string except 'all' or 'none' "
"(those are predefined names for the rules that match all or nothing "
"respectively). The name 'ACLName' can be referenced from other "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"parts of the configuration file, for example in _`access_rules`_ "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"option. The rules of 'ACLName' are represented by mapping "
"'pass:[{ACLType: ACLValue}]'. These can be one of the following:")},
[{user,
#{value => ?T("Username"),
desc =>
?T("If 'Username' is in the form of \"user@server\", "
"the rule matches a JID against this value. "
"Otherwise, if 'Username' is in the form of \"user\", "
"the rule matches any JID that has 'Username' in the node part "
"as long as the server part of this JID is any virtual "
"host served by ejabberd.")}},
{server,
#{value => ?T("Server"),
desc =>
?T("The rule matches any JID from server 'Server'. "
"The value of 'Server' must be a valid "
"hostname or an IP address.")}},
{resource,
#{value => ?T("Resource"),
desc =>
?T("The rule matches any JID with a resource 'Resource'.")}},
{ip,
#{value => ?T("Network"),
desc =>
?T("The rule matches any IP address from the 'Network'.")}},
{user_regexp,
#{value => ?T("Regexp"),
desc =>
?T("If 'Regexp' is in the form of \"regexp@server\", the rule "
"matches any JID with node part matching regular expression "
"\"regexp\" as long as the server part of this JID is equal "
"to \"server\". If 'Regexp' is in the form of \"regexp\", the rule "
"matches any JID with node part matching regular expression "
"\"regexp\" as long as the server part of this JID is any virtual "
"host served by ejabberd.")}},
{server_regexp,
#{value => ?T("Regexp"),
desc =>
?T("The rule matches any JID from the server that "
"matches regular expression 'Regexp'.")}},
{resource_regexp,
#{value => ?T("Regexp"),
desc =>
?T("The rule matches any JID with a resource that "
"matches regular expression 'Regexp'.")}},
{node_regexp,
#{value => ?T("user_regexp@server_regexp"),
desc =>
?T("The rule matches any JID with node part matching regular "
"expression 'user_regexp' and server part matching regular "
"expression 'server_regexp'.")}},
{user_glob,
#{value => ?T("Pattern"),
desc =>
?T("Same as 'user_regexp', but matching is performed on a "
"specified 'Pattern' according to the rules used by the "
"Unix shell.")}},
{server_glob,
#{value => ?T("Pattern"),
desc =>
?T("Same as 'server_regexp', but matching is performed on a "
"specified 'Pattern' according to the rules used by the "
"Unix shell.")}},
{resource_glob,
#{value => ?T("Pattern"),
desc =>
?T("Same as 'resource_regexp', but matching is performed on a "
"specified 'Pattern' according to the rules used by the "
"Unix shell.")}},
{node_glob,
#{value => ?T("Pattern"),
desc =>
?T("Same as 'node_regexp', but matching is performed on a "
"specified 'Pattern' according to the rules used by the "
"Unix shell.")}}]},
{access_rules,
#{value => "{AccessName: {allow|deny: ACLRules|ACLName}}",
desc =>
Improve explanation of s2s_access option. Add link to access_rules option
2022-02-02 18:24:36 +01:00
?T("This option defines "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"_`basic.md#access-rules|Access Rules`_. "
Improve explanation of s2s_access option. Add link to access_rules option
2022-02-02 18:24:36 +01:00
"Each access rule is "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"assigned a name that can be referenced from other parts "
"of the configuration file (mostly from 'access' options of "
"ejabberd modules). Each rule definition may contain "
"arbitrary number of 'allow' or 'deny' sections, and each "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"section may contain any number of ACL rules (see _`acl`_ option). "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"There are no access rules defined by default."),
example =>
["access_rules:",
" configure:",
" allow: admin",
" something:",
" deny: someone",
" allow: all",
" s2s_banned:",
" deny: problematic_hosts",
" deny: banned_forever",
" deny:",
" ip: 222.111.222.111/32",
" deny:",
" ip: 111.222.111.222/32",
" allow: all",
" xmlrpc_access:",
" allow:",
" user: peter@example.com",
" allow:",
" user: ivone@example.com",
" allow:",
" user: bot@example.com",
" ip: 10.0.0.0/24"]}},
{acme,
#{value => ?T("Options"),
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("_`basic.md#acme|ACME`_ configuration, to automatically "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"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 'Options' are:"),
example =>
["acme:",
" ca_url: https://acme-v02.api.letsencrypt.org/directory",
" contact:",
" - mailto:admin@domain.tld",
" - mailto:bot@domain.tld",
" auto: true",
" cert_type: rsa"]},
[{ca_url,
#{value => ?T("URL"),
desc =>
?T("The ACME directory URL used as an entry point "
"for the ACME server. The default value is "
"<https://acme-v02.api.letsencrypt.org/directory> - "
"the directory URL of Let's Encrypt authority.")}},
{contact,
#{value => ?T("[Contact, ...]"),
desc =>
?T("A list of contact addresses (typically emails) "
"where an ACME server will send notifications "
"when problems occur. The value of 'Contact' must "
"be in the form of \"scheme:address\" (e.g. "
"\"mailto:user@domain.tld\"). The default "
"is an empty list which means an ACME server "
"will send no notices.")}},
{auto,
#{value => "true | false",
desc =>
?T("Whether to automatically request certificates for "
"all configured domains (that yet have no a certificate) "
"on server start or configuration reload. The default is 'true'.")}},
{cert_type,
#{value => "rsa | ec",
desc =>
?T("A type of a certificate key. Available values are "
"'ec' and 'rsa' for EC and RSA certificates respectively. "
"It's better to have RSA certificates for the purpose "
"of backward compatibility with legacy clients and servers, "
"thus the default is 'rsa'.")}}]},
{allow_contrib_modules,
#{value => "true | false",
desc =>
?T("Whether to allow installation of third-party modules or not. "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"See _`../../developer/extending-ejabberd/modules.md#ejabberd-contrib|ejabberd-contrib`_ "
"documentation section. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"The default value is 'true'.")}},
{allow_multiple_connections,
#{value => "true | false",
desc =>
?T("This option is only used when the anonymous mode is enabled. "
"Setting it to 'true' means that the same username can be "
"taken multiple times in anonymous login mode if different "
"resource are used to connect. This option is only useful "
"in very special occasions. The default value is 'false'.")}},
{anonymous_protocol,
#{value => "login_anon | sasl_anon | both",
desc =>
Improve formatting and add sections links
2021-08-23 13:40:19 +02:00
[?T("Define what anonymous protocol will be used: "), "",
?T("* 'login_anon' means that the anonymous login method will be used. "), "",
?T("* 'sasl_anon' means that the SASL Anonymous method will be used. "), "",
?T("* 'both' means that SASL Anonymous and login anonymous are both "
"enabled."), "",
?T("The default value is 'sasl_anon'."), ""]}},
Quick document with forward link api_permissions
2020-01-27 13:00:08 +01:00
{api_permissions,
#{value => "[Permission, ...]",
desc =>
?T("Define the permissions for API access. Please consult the "
"ejabberd Docs web -> For Developers -> ejabberd ReST API -> "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"_`../../developer/ejabberd-api/permissions.md|API Permissions`_.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{append_host_config,
#{value => "{Host: Options}",
desc =>
?T("To define specific ejabberd modules in a virtual host, "
"you can define the global 'modules' option with the common modules, "
"and later add specific modules to certain virtual hosts. "
"To accomplish that, 'append_host_config' option can be used.")}},
{auth_cache_life_time,
#{value => "timeout()",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_life_time`_, but applied to authentication cache "
"only. If not set, the value from _`cache_life_time`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{auth_cache_missed,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_missed`_, but applied to authentication cache "
"only. If not set, the value from _`cache_missed`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{auth_cache_size,
#{value => "pos_integer() | infinity",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_size`_, but applied to authentication cache "
"only. If not set, the value from _`cache_size`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{auth_method,
#{value => "[mnesia | sql | anonymous | external | jwt | ldap | pam, ...]",
desc =>
?T("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 '[mnesia]'.")}},
Add ejabberd_auth_http auth_opts brief description
2020-04-01 22:40:28 +02:00
{auth_opts,
Minor fixes in doc
2020-04-09 12:01:05 +02:00
#{value => "[Option, ...]",
desc =>
?T("This is used by the contributed module "
Add ejabberd_auth_http auth_opts brief description
2020-04-01 22:40:28 +02:00
"'ejabberd_auth_http' that can be installed from the "
Improve formatting and add sections links
2021-08-23 13:40:19 +02:00
"https://github.com/processone/ejabberd-contrib[ejabberd-contrib] "
"Git repository. Please refer to that "
Minor fixes in doc
2020-04-09 12:01:05 +02:00
"module's README file for details.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{auth_password_format,
#{value => "plain | scram",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "improved in 20.01",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
Improve formatting and add sections links
2021-08-23 13:40:19 +02:00
[?T("The option defines in what format the users passwords "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"are stored, plain text or in _`authentication.md#scram|SCRAM`_ format:"), "",
Improve formatting and add sections links
2021-08-23 13:40:19 +02:00
?T("* 'plain': The password is stored as plain text "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"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), "
Minor improvements in auth_password_format documentation
2023-12-01 00:07:21 +01:00
"SASL PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1/256/512(-PLUS). "), "",
Improve formatting and add sections links
2021-08-23 13:40:19 +02:00
?T("* 'scram': The password is not stored, only some information "
Rephrase sentences to avoid using "allow to + verb"
2024-01-11 13:23:45 +01:00
"required to verify the hash provided by the client. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"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: "
Minor improvements in auth_password_format documentation
2023-12-01 00:07:21 +01:00
"SASL PLAIN and SASL SCRAM-SHA-1/256/512(-PLUS). The SCRAM variant "
"depends on the _`auth_scram_hash`_ option."), "",
?T("The default value is 'plain'."), ""]}},
Document auth_scram_hash option
2020-12-15 15:40:16 +01:00
{auth_scram_hash,
#{value => "sha | sha256 | sha512",
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("Hash algorithm that should be used to store password in _`authentication.md#scram|SCRAM`_ format. "
Reword auth_scram_hash info (#3448)
2020-12-15 17:47:56 +01:00
"You shouldn't change this if you already have passwords generated with "
"a different algorithm - users that have such passwords will not be able "
Update documentation to match the implemented options values (#3675)
2021-09-14 11:24:49 +02:00
"to authenticate. The default value is 'sha'.")}},
Add `auth_external_user_exists_check` option This makes `user_check` hook work better with authentication methods that don't have a way to determine if user exists (like is the case for jwt and cert based authentication), and as result will improve mod_offline and mod_mam handling of offline messages to those users. This reuses information stored by `mod_last` for this purpose. Should fix issue #3377.
2023-10-11 14:16:51 +02:00
{auth_external_user_exists_check,
#{value => "true | false",
Dcoument ejabberd version number in the new options
2023-10-02 10:54:24 +02:00
note => "added in 23.10",
Add `auth_external_user_exists_check` option This makes `user_check` hook work better with authentication methods that don't have a way to determine if user exists (like is the case for jwt and cert based authentication), and as result will improve mod_offline and mod_mam handling of offline messages to those users. This reuses information stored by `mod_last` for this purpose. Should fix issue #3377.
2023-10-11 14:16:51 +02:00
desc =>
?T("Supplement check for user existence based on 'mod_last' data, for authentication "
Fix a few spelling errors
2024-01-11 12:59:29 +01:00
"methods that don't have a way to reliably tell if a user exists (like is the case for "
Add `auth_external_user_exists_check` option This makes `user_check` hook work better with authentication methods that don't have a way to determine if user exists (like is the case for jwt and cert based authentication), and as result will improve mod_offline and mod_mam handling of offline messages to those users. This reuses information stored by `mod_last` for this purpose. Should fix issue #3377.
2023-10-11 14:16:51 +02:00
"'jwt' and certificate based authentication). This helps with processing offline message "
"for those users. The default value is 'true'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{auth_use_cache,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`use_cache`_, but applied to authentication cache "
"only. If not set, the value from _`use_cache`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{c2s_cafile,
#{value => ?T("Path"),
desc =>
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
[?T("Full path to a file containing one or more CA certificates "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"in PEM format. All client certificates should be signed by "
"one of these root CA certificates and should contain the "
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
"corresponding JID(s) in 'subjectAltName' field. "
"There is no default value."), "",
Use shorthands provided by docs.ejabberd.im Makefile, fix markdown syntax
2024-03-07 01:09:53 +01:00
?T("You can use _`host_config`_ to specify this option per-vhost."), "",
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("To set a specific file per listener, use the listener's _`listen-options.md#cafile|cafile`_ option. Please notice that 'c2s_cafile' overrides the listener's 'cafile' option."), ""
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
]}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{c2s_ciphers,
#{value => "[Cipher, ...]",
desc =>
?T("A list of OpenSSL ciphers to use for c2s connections. "
"The default value is shown in the example below:"),
example =>
["c2s_ciphers:",
" - HIGH",
" - \"!aNULL\"",
" - \"!eNULL\"",
" - \"!3DES\"",
" - \"@STRENGTH\""]}},
{c2s_dhfile,
#{value => ?T("Path"),
desc =>
?T("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.")}},
{c2s_protocol_options,
#{value => "[Option, ...]",
desc =>
?T("List of general SSL options to use for c2s connections. "
"These map to OpenSSL's 'set_options()'. The default value is "
"shown in the example below:"),
example =>
["c2s_protocol_options:",
" - no_sslv3",
" - cipher_server_preference",
" - no_compression"]}},
{c2s_tls_compression,
#{value => "true | false",
desc =>
?T("Whether to enable or disable TLS compression for c2s connections. "
"The default value is 'false'.")}},
{ca_file,
#{value => ?T("Path"),
desc =>
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
[?T("Path to a file of CA root certificates. "
"The default is to use system defined file if possible."), "",
Use shorthands provided by docs.ejabberd.im Makefile, fix markdown syntax
2024-03-07 01:09:53 +01:00
?T("For server connections, this 'ca_file' option is overridden by the _`s2s_cafile`_ option."), ""
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
]}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{captcha_cmd,
Add support to define module instead of path to script
2022-12-26 10:52:16 +01:00
#{value => ?T("Path | ModuleName"),
Annotate options that change in ejabberd 23.01
2023-01-11 15:17:27 +01:00
note => "improved in 23.01",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("Full path to a script that generates _`basic.md#captcha|CAPTCHA`_ images. "
captcha_url option now accepts 'auto' value, and it's the default
2023-02-01 11:52:47 +01:00
"'@VERSION@' is replaced with ejabberd version number in 'XX.YY' format. "
"'@SEMVER@' is replaced with ejabberd version number in semver format "
Support @VERSION@ and @SEMVER@ in captcha_cmd option
2022-05-30 11:46:19 +02:00
"when compiled with Elixir's mix, or XX.YY format otherwise. "
Add support to define module instead of path to script
2022-12-26 10:52:16 +01:00
"Alternatively, it can be the name of a module that implements ejabberd CAPTCHA support. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"There is no default value: when this option is not "
Support @VERSION@ and @SEMVER@ in captcha_cmd option
2022-05-30 11:46:19 +02:00
"set, CAPTCHA functionality is completely disabled."),
example =>
[{?T("When using the ejabberd installers or container image, the example captcha scripts can be used like this:"),
["captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh"]}]}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{captcha_limit,
#{value => "pos_integer() | infinity",
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("Maximum number of _`basic.md#captcha|CAPTCHA`_ generated images per minute for "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"any given JID. The option is intended to protect the server "
"from CAPTCHA DoS. The default value is 'infinity'.")}},
{captcha_host,
Minor fixes in doc
2020-04-09 12:01:05 +02:00
#{value => "String",
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
desc => ?T("Deprecated. Use _`captcha_url`_ instead.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{captcha_url,
captcha_url option now accepts 'auto' value, and it's the default
2023-02-01 11:52:47 +01:00
#{value => ?T("URL | auto | undefined"),
Update version notes of options and commands
2023-04-17 12:34:30 +02:00
note => "improved in 23.04",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("An URL where _`basic.md#captcha|CAPTCHA`_ requests should be sent. NOTE: you need "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"to configure 'request_handlers' for 'ejabberd_http' listener "
captcha_url option now accepts 'auto' value, and it's the default
2023-02-01 11:52:47 +01:00
"as well. "
"If set to 'auto', it builds the URL using a 'request_handler' "
"already enabled, with encryption if available. "
"If set to 'undefined', it builds the URL using "
"the deprecated _`captcha_host`_ + /captcha. "
"The default value is 'auto'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{certfiles,
#{value => "[Path, ...]",
desc =>
?T("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: 'ejabberd_c2s', 'ejabberd_http' and so on. "
"NOTE: if you modify the certificate files or change the value "
"of the option, run 'ejabberdctl reload-config' in order to "
"rebuild and reload the certificate chains."),
example =>
[{?T("If you use https://letsencrypt.org[Let's Encrypt] certificates "
"for your domain \"domain.tld\", the configuration will look "
"like this:"),
["certfiles:",
" - /etc/letsencrypt/live/domain.tld/fullchain.pem",
" - /etc/letsencrypt/live/domain.tld/privkey.pem"]}]}},
{cluster_backend,
#{value => ?T("Backend"),
desc =>
?T("A database backend to use for storing information about "
"cluster. The only available value so far is 'mnesia'.")}},
{cluster_nodes,
#{value => "[Node, ...]",
desc =>
?T("A list of Erlang nodes to connect on ejabberd startup. "
"This option is mostly intended for ejabberd customization "
Fix some English typos
2020-04-21 20:58:01 +02:00
"and sophisticated setups. The default value is an empty list.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{define_macro,
#{value => "{MacroName: MacroValue}",
desc =>
?T("Defines a macro. The value can be any valid arbitrary "
"YAML value. For convenience, it's recommended to define "
"a 'MacroName' 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 'MacroValue' in the definition of another macro."),
example =>
["define_macro:",
" DEBUG: debug",
" LOG_LEVEL: DEBUG",
" USERBOB:",
" user: bob@localhost",
"",
"loglevel: LOG_LEVEL",
"",
"acl:",
" admin: USERBOB"]}},
Add option to disable XEP-0474: SASL SCRAM Downgrade Protection support Looks like clients using strophejs aren't able to authenticate when we add data required by that spec to scram packets, so at least give a way to disable this until clients will be fixed.
2024-01-16 12:03:35 +01:00
{disable_sasl_scram_downgrade_protection,
#{value => "true | false",
desc =>
?T("Allows to disable sending data required by "
"'XEP-0474: SASL SCRAM Downgrade Protection'. "
"There are known buggy clients (like those that use strophejs 1.6.2) "
"which will not be able to authenticatate when servers sends data from "
"that specification. This options allows server to disable it to allow "
"even buggy clients connects, but in exchange decrease MITM protection. "
"The default value of this option is 'false' which enables this extension.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{disable_sasl_mechanisms,
#{value => "[Mechanism, ...]",
desc =>
?T("Specify a list of SASL mechanisms (such as 'DIGEST-MD5' or "
"'SCRAM-SHA1') that should not be offered to the client. "
"For convenience, the value of 'Mechanism' is case-insensitive. "
"The default value is an empty list, i.e. no mechanisms "
"are disabled by default.")}},
{domain_balancing,
#{value => "{Domain: Options}",
desc =>
?T("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 'Domain', available "
"'Options' are:"),
example =>
["domain_balancing:",
" component.domain.tld:",
" type: destination",
" component_number: 5",
" transport.example.org:",
" type: bare_source"]},
[{type,
#{value => "random | source | destination | bare_source | bare_destination",
desc =>
?T("How to deliver stanzas to connected components: "
"'random' - an instance is chosen at random; "
"'destination' - an instance is chosen by the full JID of "
"the packet's 'to' attribute; "
"'source' - by the full JID of the packet's 'from' attribute; "
Fix a few spelling errors
2024-01-11 12:59:29 +01:00
"'bare_destination' - by the bare JID (without resource) "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"of the packet's 'to' attribute; "
"'bare_source' - by the bare JID (without resource) of the "
"packet's 'from' attribute is used. The default value is 'random'.")}},
{component_number,
#{value => "2..1000",
desc =>
?T("The number of components to balance.")}}]},
Document some global options
2020-01-24 13:42:09 +01:00
{extauth_pool_name,
#{value => ?T("Name"),
desc =>
?T("Define the pool name appendix, so the full pool name will be "
"'extauth_pool_Name'. The default value is the hostname.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{extauth_pool_size,
#{value => ?T("Size"),
desc =>
?T("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.")}},
{extauth_program,
#{value => ?T("Path"),
desc =>
?T("Indicate in this option the full path to the external "
"authentication script. The script must be executable by ejabberd.")}},
Document some global options
2020-01-24 13:42:09 +01:00
{ext_api_headers,
#{value => "Headers",
desc =>
?T("String of headers (separated with commas ',') that will be "
"provided by ejabberd when sending ReST requests. "
"The default value is an empty string of headers: '\"\"'.")}},
{ext_api_http_pool_size,
#{value => "pos_integer()",
desc =>
?T("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: '100'.")}},
{ext_api_path_oauth,
#{value => "Path",
desc =>
?T("Define the base URI path when performing OAUTH ReST requests. "
"The default value is: '\"/oauth\"'.")}},
{ext_api_url,
#{value => "URL",
desc =>
?T("Define the base URI when performing ReST requests. "
"The default value is: '\"http://localhost/api\"'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{fqdn,
#{value => ?T("Domain"),
desc =>
?T("A fully qualified domain name that will be used in "
"SASL DIGEST-MD5 authentication. The default is detected "
"automatically.")}},
{hide_sensitive_log_data,
#{value => "true | false",
desc =>
?T("A privacy option to not log sensitive data "
"(mostly IP addresses). The default value "
"is 'false' for backward compatibility.")}},
{host_config,
#{value => "{Host: Options}",
desc =>
?T("The option is used to redefine 'Options' for virtual host "
"'Host'. In the example below LDAP authentication method "
"will be used on virtual host 'domain.tld' and SQL method "
"will be used on virtual host 'example.org'."),
example =>
["hosts:",
" - domain.tld",
" - example.org",
"",
"auth_method:",
" - sql",
"",
"host_config:",
" domain.tld:",
" auth_method:",
" - ldap"]}},
{include_config_file,
#{value => "[Filename, ...\\] | {Filename: Options}",
desc =>
?T("Read additional configuration from 'Filename'. If the "
"value is provided in 'pass:[{Filename: Options}]' format, the "
"'Options' must be one of the following:")},
[{disallow,
#{value => "[OptionName, ...]",
desc =>
?T("Disallows the usage of those options in the included "
"file 'Filename'. The options that match this criteria "
"are not accepted. The default value is an empty list.")}},
{allow_only,
#{value => "[OptionName, ...]",
desc =>
?T("Allows only the usage of those options in the included "
"file 'Filename'. The options that do not match this "
"criteria are not accepted. The default value is to include "
"all options.")}}]},
New option install_contrib_modules This option is read during ejabberd start or config reload. It installs the listed modules which aren't yet installed, as long as allow_contrib_modules is not disabled. Edit ejabberd.yml and configure the desired ejabberd-contrib modules, add them in the install_contrib_modules option, finally start ejabberd (or reload config).
2023-05-17 17:09:09 +02:00
{install_contrib_modules,
#{value => "[Module, ...]",
Dcoument ejabberd version number in the new options
2023-10-02 10:54:24 +02:00
note => "added in 23.10",
New option install_contrib_modules This option is read during ejabberd start or config reload. It installs the listed modules which aren't yet installed, as long as allow_contrib_modules is not disabled. Edit ejabberd.yml and configure the desired ejabberd-contrib modules, add them in the install_contrib_modules option, finally start ejabberd (or reload config).
2023-05-17 17:09:09 +02:00
desc =>
?T("Modules to install from "
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
"_`../../developer/extending-ejabberd/modules.md#ejabberd-contrib|ejabberd-contrib`_ "
"at start time. "
New option install_contrib_modules This option is read during ejabberd start or config reload. It installs the listed modules which aren't yet installed, as long as allow_contrib_modules is not disabled. Edit ejabberd.yml and configure the desired ejabberd-contrib modules, add them in the install_contrib_modules option, finally start ejabberd (or reload config).
2023-05-17 17:09:09 +02:00
"The default value is an empty list of modules: '[]'.")}},
Document some global options
2020-01-24 13:42:09 +01:00
{jwt_auth_only_rule,
#{value => ?T("AccessName"),
desc =>
?T("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 'none'.")}},
{jwt_jid_field,
#{value => ?T("FieldName"),
desc =>
?T("By default, the JID is defined in the '\"jid\"' JWT field. "
Rephrase sentences to avoid using "allow to + verb"
2024-01-11 13:23:45 +01:00
"In this option you can specify other JWT field name "
Document some global options
2020-01-24 13:42:09 +01:00
"where the JID is defined.")}},
{jwt_key,
#{value => ?T("FilePath"),
desc =>
?T("Path to the file that contains the JWK Key. "
"The default value is 'undefined'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{language,
#{value => ?T("Language"),
desc =>
?T("The option defines the default language of server strings "
"that can be seen by XMPP clients. If an XMPP client does not "
Update documentation to match the implemented options values (#3675)
2021-09-14 11:24:49 +02:00
"possess 'xml:lang' attribute, the specified language is used. "
"The default value is '\"en\"'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{ldap_servers,
#{value => "[Host, ...]",
desc =>
?T("A list of IP addresses or DNS names of your LDAP servers. "
"The default value is '[localhost]'.")}},
{ldap_backups,
#{value => "[Host, ...]",
desc =>
?T("A list of IP addresses or DNS names of LDAP backup servers. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"When no servers listed in _`ldap_servers`_ option are reachable, "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"ejabberd will try to connect to these backup servers. "
"The default is an empty list, i.e. no backup servers specified. "
"WARNING: ejabberd doesn't 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.")}},
{ldap_encrypt,
#{value => "tls | none",
desc =>
?T("Whether to encrypt LDAP connection using TLS or not. "
"The default value is 'none'. NOTE: STARTTLS encryption "
"is not supported.")}},
{ldap_tls_certfile,
#{value => ?T("Path"),
desc =>
?T("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.")}},
{ldap_tls_verify,
#{value => "false | soft | hard",
desc =>
?T("This option specifies whether to verify LDAP server "
"certificate or not when TLS is enabled. When 'hard' is set, "
"ejabberd doesn't proceed if the certificate is invalid. "
"When 'soft' is set, ejabberd proceeds even if the check has failed. "
"The default is 'false', which means no checks are performed.")}},
{ldap_tls_cacertfile,
#{value => ?T("Path"),
desc =>
?T("A path to a file containing PEM encoded CA certificates. "
"This option is required when TLS verification is enabled.")}},
{ldap_tls_depth,
#{value => ?T("Number"),
desc =>
?T("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 '2' thus means that a chain can at most contain "
"peer cert, CA cert, next CA cert, and an additional CA cert. "
"The default value is '1'.")}},
{ldap_port,
#{value => "1..65535",
desc =>
?T("Port to connect to your LDAP server. The default port is "
"'389' if encryption is disabled and '636' if encryption is "
"enabled.")}},
{ldap_rootdn,
#{value => "RootDN",
desc =>
?T("Bind Distinguished Name. The default value is an empty "
"string, which means \"anonymous connection\".")}},
{ldap_password,
#{value => ?T("Password"),
desc =>
?T("Bind password. The default value is an empty string.")}},
{ldap_deref_aliases,
#{value => "never | always | finding | searching",
desc =>
?T("Whether to dereference aliases or not. "
"The default value is 'never'.")}},
{ldap_base,
#{value => "Base",
desc =>
?T("LDAP base directory which stores users accounts. "
"There is no default value: you must set the option "
"in order for LDAP connections to work properly.")}},
{ldap_uids,
#{value => "[Attr\\] | {Attr: AttrFormat}",
desc =>
?T("LDAP attributes which hold a list of attributes to use "
"as alternatives for getting the JID, where 'Attr' is "
"an LDAP attribute which holds the user's part of the JID and "
"'AttrFormat' must contain one and only one pattern variable "
"\"%u\" which will be replaced by the user's part of the JID. "
"For example, \"%u@example.org\". If the value is in the form "
"of '[Attr]' then 'AttrFormat' is assumed to be \"%u\".")}},
{ldap_filter,
#{value => ?T("Filter"),
desc =>
?T("An LDAP filter as defined in "
"https://tools.ietf.org/html/rfc4515[RFC4515]. "
"There is no default value. Example: "
Replace Jabber->XMPP and Ejabberd (thanks to Neustradamus)(#3469)
2021-01-11 20:18:28 +01:00
"\"(&(objectClass=shadowAccount)(memberOf=XMPP Users))\". "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"NOTE: don't forget to close brackets and don't use superfluous "
"whitespaces. Also you must not use \"uid\" attribute in the "
"filter because this attribute will be appended to the filter "
"automatically.")}},
{ldap_dn_filter,
#{value => "{Filter: FilterAttrs}",
desc =>
?T("This filter is applied on the results returned by the main "
"filter. The filter performs an additional LDAP lookup to make "
"the complete result. This is useful when you are unable to "
"define all filter rules in 'ldap_filter'. You can define "
"\"%u\", \"%d\", \"%s\" and \"%D\" pattern variables in 'Filter': "
"\"%u\" is replaced by a user's part of the JID, \"%d\" is "
"replaced by the corresponding domain (virtual host), all \"%s\" "
"variables are consecutively replaced by values from the attributes "
"in 'FilterAttrs' and \"%D\" is replaced by Distinguished Name from "
"the result set. There is no default value, which means the "
"result is not filtered. WARNING: Since this filter makes "
"additional LDAP lookups, use it only as the last resort: "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"try to define all filter rules in _`ldap_filter`_ option if possible."),
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
example =>
["ldap_dn_filter:",
" \"(&(name=%s)(owner=%D)(user=%u@%d))\": [sn]"]}},
{log_rotate_count,
#{value => ?T("Number"),
desc =>
?T("The number of rotated log files to keep. "
Copy log_rotate_count explanation from docs site
2021-08-23 12:48:06 +02:00
"The default value is '1', which means that only keeps "
"`ejabberd.log.0`, `error.log.0` and `crash.log.0`.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{log_rotate_size,
Clarify documentation of log_rotate_size option (#3462)
2021-01-04 13:04:56 +01:00
#{value => "pos_integer() | infinity",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("The size (in bytes) of a log file to trigger rotation. "
Clarify documentation of log_rotate_size option (#3462)
2021-01-04 13:04:56 +01:00
"If set to 'infinity', log rotation is disabled. "
"The default value is '10485760' (that is, 10 Mb).")}},
Add log_burst_limit_* options (#3865) * Add log_burst_limit_* options On our ejabberd deployment we were sometimes seeing more than 500 msgs/sec of legitimate traffic, however this was getting silently dropped. Provide config options to enable this limit to be configured from the config file. * Pass new logging vars in via ejabberdctl
2022-08-01 12:07:54 +02:00
{log_burst_limit_count,
#{value => ?T("Number"),
Annotate new options
2022-09-30 17:51:41 +02:00
note => "added in 22.10",
Add log_burst_limit_* options (#3865) * Add log_burst_limit_* options On our ejabberd deployment we were sometimes seeing more than 500 msgs/sec of legitimate traffic, however this was getting silently dropped. Provide config options to enable this limit to be configured from the config file. * Pass new logging vars in via ejabberdctl
2022-08-01 12:07:54 +02:00
desc =>
?T("The number of messages to accept in "
"`log_burst_limit_window_time` period before starting to "
"drop them. Default 500")}},
{log_burst_limit_window_time,
#{value => ?T("Number"),
Annotate new options
2022-09-30 17:51:41 +02:00
note => "added in 22.10",
Add log_burst_limit_* options (#3865) * Add log_burst_limit_* options On our ejabberd deployment we were sometimes seeing more than 500 msgs/sec of legitimate traffic, however this was getting silently dropped. Provide config options to enable this limit to be configured from the config file. * Pass new logging vars in via ejabberdctl
2022-08-01 12:07:54 +02:00
desc =>
?T("The time period to rate-limit log messages "
"by. Defaults to 1 second.")}},
Document the new log_modules_fully option
2022-12-02 16:38:28 +01:00
{log_modules_fully,
Fix doc of log_modules_fully allowed value
2023-01-10 15:11:32 +01:00
#{value => "[Module, ...]",
Annotate options that change in ejabberd 23.01
2023-01-11 15:17:27 +01:00
note => "added in 23.01",
Document the new log_modules_fully option
2022-12-02 16:38:28 +01:00
desc =>
Fix doc of log_modules_fully allowed value
2023-01-10 15:11:32 +01:00
?T("List of modules that will log everything "
Document the new log_modules_fully option
2022-12-02 16:38:28 +01:00
"independently from the general loglevel option.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{max_fsm_queue,
#{value => ?T("Size"),
desc =>
?T("This option specifies the maximum number of elements "
"in the queue of the FSM (Finite State Machine). Roughly "
"speaking, each message in such queues represents one "
"XML stanza queued to be sent into its relevant outgoing "
"stream. If queue size reaches the limit (because, for "
"example, the receiver of stanzas is too slow), the FSM "
"and the corresponding connection (if any) will be terminated "
"and error message will be logged. The reasonable value for "
"this option depends on your hardware configuration. "
"The allowed values are positive integers. "
"The default value is '10000'.")}},
{negotiation_timeout,
#{value => "timeout()",
desc =>
?T("Time to wait for an XMPP stream negotiation to complete. "
"When timeout occurs, the corresponding XMPP stream is closed. "
Document recent change from 7d4330b57
2023-12-13 23:26:48 +01:00
"The default value is '120' seconds.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{net_ticktime,
#{value => "timeout()",
desc =>
?T("This option can be used to tune tick time parameter of "
"'net_kernel'. It tells Erlang VM how often nodes should check "
"if intra-node 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. "
Update documentation to match the implemented options values (#3675)
2021-09-14 11:24:49 +02:00
"The default value is '1 minute'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{new_sql_schema,
#{value => "true | false",
desc =>
{?T("Whether to use 'new' SQL schema. All schemas are located "
"at <https://github.com/processone/ejabberd/tree/~s/sql>. "
Fix some English typos
2020-04-21 20:58:01 +02:00
"There are two schemas available. The default legacy schema "
Rephrase sentences to avoid using "allow to + verb"
2024-01-11 13:23:45 +01:00
"stores one XMPP domain into one ejabberd database. "
"The 'new' schema can handle several XMPP domains in a "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"single ejabberd database. Using this 'new' 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 '--enable-new-sql-schema' which is set "
"at compile time."),
[binary:part(ejabberd_config:version(), {0,5})]}}},
Automatically create and update SQL schema
2023-09-28 02:37:36 +02:00
{update_sql_schema,
#{value => "true | false",
Update version number of new commands, options and protocols to 24.06
2024-06-27 10:54:09 +02:00
note => "updated in 24.06",
Automatically create and update SQL schema
2023-09-28 02:37:36 +02:00
desc =>
?T("Allow ejabberd to update SQL schema. "
Update version number of new commands, options and protocols to 24.06
2024-06-27 10:54:09 +02:00
"This option was added in ejabberd 23.10, "
"and enabled by default since 24.06. "
Automatically create and update SQL schema
2023-09-28 02:37:36 +02:00
"The default value is 'true'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{oauth_access,
#{value => ?T("AccessName"),
desc => ?T("By default creating OAuth tokens is not allowed. "
"To define which users can create OAuth tokens, "
"you can refer to an ejabberd access rule in the "
"'oauth_access' option. Use 'all' to allow everyone "
"to create tokens.")}},
{oauth_cache_life_time,
#{value => "timeout()",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_life_time`_, but applied to OAuth cache "
"only. If not set, the value from _`cache_life_time`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{oauth_cache_missed,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_missed`_, but applied to OAuth cache "
"only. If not set, the value from _`cache_missed`_ will be used.")}},
Document the recent oauth_cache_rest_failure_life_time option
2021-01-27 17:42:36 +01:00
{oauth_cache_rest_failure_life_time,
#{value => "timeout()",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "added in 21.01",
Document the recent oauth_cache_rest_failure_life_time option
2021-01-27 17:42:36 +01:00
desc =>
?T("The time that a failure in OAuth ReST is cached. "
"The default value is 'infinity'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{oauth_cache_size,
#{value => "pos_integer() | infinity",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_size`_, but applied to OAuth cache "
"only. If not set, the value from _`cache_size`_ will be used.")}},
Document some global options
2020-01-24 13:42:09 +01:00
{oauth_client_id_check,
#{value => "allow | db | deny",
desc =>
?T("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 'allow'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{oauth_use_cache,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`use_cache`_, but applied to OAuth cache "
"only. If not set, the value from _`use_cache`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{oauth_db_type,
#{value => "mnesia | sql",
desc =>
?T("Database backend to use for OAuth authentication. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"The default value is picked from _`default_db`_ option, or "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"if it's not set, 'mnesia' will be used.")}},
{oauth_expire,
#{value => "timeout()",
desc =>
?T("Time during which the OAuth token is valid, in seconds. "
"After that amount of time, the token expires and the delegated "
"credential cannot be used and is removed from the database. "
"The default is '4294967' seconds.")}},
{oom_killer,
#{value => "true | false",
desc =>
?T("Enable or disable OOM (out-of-memory) killer. "
"When system memory raises above the limit defined in "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`oom_watermark`_ option, ejabberd triggers OOM killer "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"to terminate most memory consuming Erlang processes. "
"Note that in order to maintain functionality, ejabberd only "
"attempts to kill transient processes, such as those managing "
"client sessions, s2s or database connections. "
"The default value is 'true'.")}},
{oom_queue,
#{value => ?T("Size"),
desc =>
?T("Trigger OOM killer when some of the running Erlang processes "
"have messages queue above this 'Size'. Note that "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"such processes won't be killed if _`oom_killer`_ option is set "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"to 'false' or if 'oom_watermark' is not reached yet.")}},
{oom_watermark,
#{value => ?T("Percent"),
desc =>
?T("A percent of total system memory consumed at which "
"OOM killer should be activated with some of the processes "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"possibly be killed (see _`oom_killer`_ option). Later, when "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"memory drops below this 'Percent', OOM killer is deactivated. "
"The default value is '80' percents.")}},
{outgoing_s2s_families,
Fix doc of outgoing_s2s_families default value, it changed in 25ddd7b
2023-01-10 15:06:25 +01:00
#{value => "[ipv6 | ipv4, ...]",
Annotate options that change in ejabberd 23.01
2023-01-11 15:17:27 +01:00
note => "changed in 23.01",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("Specify which address families to try, in what order. "
Fix doc of outgoing_s2s_families default value, it changed in 25ddd7b
2023-01-10 15:06:25 +01:00
"The default is '[ipv6, ipv4]' which means it first tries "
Fix typos in documentation and changelog
2023-01-16 18:22:25 +01:00
"connecting with IPv6, if that fails it tries using IPv4. "
Annotate options that change in ejabberd 23.01
2023-01-11 15:17:27 +01:00
"This option is obsolete and irrelevant when using ejabberd 23.01 "
ejabberd_options_doc.erl: Added outgoing_s2s_families deprecation notice. Signed-off-by: Jonathan Davies <jpds@protonmail.com>
2022-12-16 17:12:51 +01:00
"and Erlang/OTP 22, or newer versions of them.")}},
Document outgoing_s2s_ipv4_address and ipv6 options (#3396)
2020-11-06 15:50:50 +01:00
{outgoing_s2s_ipv4_address,
#{value => "Address",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "added in 20.12",
Document outgoing_s2s_ipv4_address and ipv6 options (#3396)
2020-11-06 15:50:50 +01:00
desc =>
?T("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 'undefined'.")}},
{outgoing_s2s_ipv6_address,
#{value => "Address",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "added in 20.12",
Document outgoing_s2s_ipv4_address and ipv6 options (#3396)
2020-11-06 15:50:50 +01:00
desc =>
?T("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 'undefined'.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{outgoing_s2s_port,
#{value => "1..65535",
desc =>
?T("A port number to use for outgoing s2s connections when the target "
"server doesn't have an SRV record. The default value is '5269'.")}},
{outgoing_s2s_timeout,
#{value => "timeout()",
desc =>
?T("The timeout in seconds for outgoing S2S connection attempts. "
"The default value is '10' seconds.")}},
{pam_service,
#{value => ?T("Name"),
desc =>
?T("This option defines the PAM service name. Refer to the PAM "
"documentation of your operation system for more information. "
"The default value is 'ejabberd'.")}},
{pam_userinfotype,
#{value => "username | jid",
desc =>
?T("This option defines what type of information about the "
"user ejabberd provides to the PAM service: only the username, "
"or the user's JID. Default is 'username'.")}},
{pgsql_users_number_estimate,
#{value => "true | false",
desc =>
?T("Whether to use PostgreSQL estimation when counting registered "
"users. The default value is 'false'.")}},
{queue_dir,
#{value => ?T("Directory"),
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("If _`queue_type`_ option is set to 'file', use this 'Directory' "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"to store file queues. The default is to keep queues inside "
"Mnesia directory.")}},
{redis_connect_timeout,
#{value => "timeout()",
desc =>
?T("A timeout to wait for the connection to be re-established "
"to the Redis server. The default is '1 second'.")}},
{redis_db,
#{value => ?T("Number"),
desc => ?T("Redis database number. The default is '0'.")}},
{redis_password,
#{value => ?T("Password"),
desc =>
?T("The password to the Redis server. "
"The default is an empty string, i.e. no password.")}},
{redis_pool_size,
#{value => ?T("Number"),
desc =>
?T("The number of simultaneous connections to the Redis server. "
"The default value is '10'.")}},
{redis_port,
#{value => "1..65535",
desc =>
?T("The port where the Redis server is accepting connections. "
"The default is '6379'.")}},
{redis_queue_type,
#{value => "ram | file",
desc =>
?T("The type of request queue for the Redis server. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"See description of _`queue_type`_ option for the explanation. "
"The default value is the value defined in _`queue_type`_ "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"or 'ram' if the latter is not set.")}},
{redis_server,
#{value => ?T("Hostname"),
desc =>
?T("A hostname or an IP address of the Redis server. "
"The default is 'localhost'.")}},
{registration_timeout,
#{value => "timeout()",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("This is a global option for module _`mod_register`_. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"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 'infinity'. "
"The default value is '600 seconds'.")}},
{resource_conflict,
#{value => "setresource | closeold | closenew",
desc =>
?T("NOTE: this option is deprecated and may be removed "
"anytime in the future versions. The possible values "
"match exactly the three possibilities described in "
"https://tools.ietf.org/html/rfc6120#section-7.7.2.2"
"[XMPP Core: section 7.7.2.2]. "
"The default value is 'closeold'. If the client "
"uses old Jabber Non-SASL authentication (XEP-0078), "
"then this option is not respected, and the action performed "
"is 'closeold'.")}},
{router_cache_life_time,
#{value => "timeout()",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_life_time`_, but applied to routing table cache "
"only. If not set, the value from _`cache_life_time`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{router_cache_missed,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_missed`_, but applied to routing table cache "
"only. If not set, the value from _`cache_missed`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{router_cache_size,
#{value => "pos_integer() | infinity",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_size`_, but applied to routing table cache "
"only. If not set, the value from _`cache_size`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{router_db_type,
Sort databases alphabetically in options doc (thanks to Neustradamus)(#3246)
2020-05-19 13:11:18 +02:00
#{value => "mnesia | redis | sql",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("Database backend to use for routing information. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"The default value is picked from _`default_ram_db`_ option, or "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"if it's not set, 'mnesia' will be used.")}},
{router_use_cache,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`use_cache`_, but applied to routing table cache "
"only. If not set, the value from _`use_cache`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{rpc_timeout,
#{value => "timeout()",
desc =>
?T("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 '5' seconds.")}},
{s2s_access,
#{value => ?T("Access"),
desc =>
Use new shorthand to provide URLs relative to ejabberd Docs
2024-03-14 12:38:03 +01:00
?T("This _`basic.md#access-rules|Access Rule`_ defines to "
Improve explanation of s2s_access option. Add link to access_rules option
2022-02-02 18:24:36 +01:00
"what remote servers can s2s connections be established. "
"The default value is 'all'; no restrictions are applied, it is"
" allowed to connect s2s to/from all remote servers.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{s2s_cafile,
#{value => ?T("Path"),
desc =>
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
[?T("A path to a file with CA root certificates that will "
"be used to authenticate s2s connections. If not set, "
Use shorthands provided by docs.ejabberd.im Makefile, fix markdown syntax
2024-03-07 01:09:53 +01:00
"the value of _`ca_file`_ will be used."), "",
?T("You can use _`host_config`_ to specify this option per-vhost."), ""
Improve explanations of cafile options
2020-07-31 17:35:24 +02:00
]}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{s2s_ciphers,
#{value => "[Cipher, ...]",
desc =>
?T("A list of OpenSSL ciphers to use for s2s connections. "
"The default value is shown in the example below:"),
example =>
["s2s_ciphers:",
" - HIGH",
" - \"!aNULL\"",
" - \"!eNULL\"",
" - \"!3DES\"",
" - \"@STRENGTH\""]}},
{s2s_dhfile,
#{value => ?T("Path"),
desc =>
?T("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.")}},
{s2s_protocol_options,
#{value => "[Option, ...]",
desc =>
?T("List of general SSL options to use for s2s connections. "
"These map to OpenSSL's 'set_options()'. The default value is "
"shown in the example below:"),
example =>
["s2s_protocol_options:",
" - no_sslv3",
" - cipher_server_preference",
" - no_compression"]}},
{s2s_tls_compression,
#{value => "true | false",
desc =>
?T("Whether to enable or disable TLS compression for s2s connections. "
"The default value is 'false'.")}},
{s2s_dns_retries,
#{value => ?T("Number"),
desc =>
?T("DNS resolving retries. The default value is '2'.")}},
{s2s_dns_timeout,
#{value => "timeout()",
desc =>
?T("The timeout for DNS resolving. The default value is '10' seconds.")}},
{s2s_max_retry_delay,
#{value => "timeout()",
desc =>
?T("The maximum allowed delay for s2s connection retry to connect after a "
"failed connection attempt. The default value is '300' seconds "
"(5 minutes).")}},
{s2s_queue_type,
#{value => "ram | file",
desc =>
?T("The type of a queue for s2s packets. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"See description of _`queue_type`_ option for the explanation. "
"The default value is the value defined in _`queue_type`_ "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"or 'ram' if the latter is not set.")}},
{s2s_timeout,
#{value => "timeout()",
desc =>
?T("A time to wait before closing an idle s2s connection. "
Bump default 's2s_timeout' value (#3653) Wait for an hour before closing an idle s2s connection. It's not uncommon for a connection to be idle for longer than ten minutes but less than an hour. For example, XEP-0410 suggests a ping interval of fifteen minutes. A longer idle timeout avoids the latency and log entries associated with constantly re-establishing such connections. Co-authored-by: Paweł Chmielowski <pawel@process-one.net>
2022-10-18 16:08:16 +02:00
"The default value is '1' hour.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{s2s_use_starttls,
#{value => "true | false | optional | required",
desc =>
?T("Whether to use STARTTLS for s2s connections. "
"The value of 'false' means STARTTLS is prohibited. "
"The value of 'true' or 'optional' means STARTTLS is enabled "
"but plain connections are still allowed. And the value of "
"'required' means that only STARTTLS connections are allowed. "
"The default value is 'false' (for historical reasons).")}},
{s2s_zlib,
#{value => "true | false",
desc =>
?T("Whether to use 'zlib' compression (as defined in "
"https://xmpp.org/extensions/xep-0138.html[XEP-0138]) or not. "
"The default value is 'false'. WARNING: this type "
"of compression is nowadays considered insecure.")}},
{shaper,
#{value => "{ShaperName: Rate}",
desc =>
?T("The option defines a set of shapers. Every shaper is assigned "
"a name 'ShaperName' that can be used in other parts of the "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"configuration file, such as _`shaper_rules`_ option. The shaper "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"itself is defined by its 'Rate', where 'Rate' stands for the "
"maximum allowed incoming rate in **bytes** per second. "
"When a connection exceeds this limit, ejabberd stops reading "
"from the socket until the average rate is again below the "
"allowed maximum. In the example below shaper 'normal' limits "
"the traffic speed to 1,000 bytes/sec and shaper 'fast' limits "
"the traffic speed to 50,000 bytes/sec:"),
example =>
["shaper:",
" normal: 1000",
" fast: 50000"]}},
{shaper_rules,
#{value => "{ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}",
desc =>
?T("An entry allowing to declaring shaper to use for matching user/hosts. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"Semantics is similar to _`access_rules`_ option, the only difference is "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"that instead using 'allow' or 'deny', a name of a shaper (defined in "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"_`shaper`_ option) or a positive number should be used."),
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
example =>
["shaper_rules:",
" connections_limit:",
" 10:",
" user: peter@example.com",
" 100: admin",
" 5: all",
" download_speed:",
" fast: admin",
" slow: anonymous_users",
" normal: all",
" log_days: 30"]}},
{sm_cache_life_time,
#{value => "timeout()",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_life_time`_, but applied to client sessions table cache "
"only. If not set, the value from _`cache_life_time`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sm_cache_missed,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_missed`_, but applied to client sessions table cache "
"only. If not set, the value from _`cache_missed`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sm_cache_size,
#{value => "pos_integer() | infinity",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`cache_size`_, but applied to client sessions table cache "
"only. If not set, the value from _`cache_size`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sm_db_type,
Sort databases alphabetically in options doc (thanks to Neustradamus)(#3246)
2020-05-19 13:11:18 +02:00
#{value => "mnesia | redis | sql",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("Database backend to use for client sessions information. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"The default value is picked from _`default_ram_db`_ option, or "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"if it's not set, 'mnesia' will be used.")}},
{sm_use_cache,
#{value => "true | false",
desc =>
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
?T("Same as _`use_cache`_, but applied to client sessions table cache "
"only. If not set, the value from _`use_cache`_ will be used.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sql_type,
Sort databases alphabetically in options doc (thanks to Neustradamus)(#3246)
2020-05-19 13:11:18 +02:00
#{value => "mssql | mysql | odbc | pgsql | sqlite",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("The type of an SQL connection. The default is 'odbc'.")}},
{sql_connect_timeout,
#{value => "timeout()",
desc =>
?T("A time to wait for connection to an SQL server to be "
"established. The default value is '5' seconds.")}},
{sql_database,
#{value => ?T("Database"),
desc =>
?T("An SQL database name. For SQLite this must be a full "
"path to a database file. The default value is 'ejabberd'.")}},
{sql_keepalive_interval,
#{value => "timeout()",
desc =>
?T("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.")}},
Document sql_odbc_driver option (copied from docs site)
2020-11-06 16:10:08 +01:00
{sql_odbc_driver,
#{value => "Path",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "added in 20.12",
Document sql_odbc_driver option (copied from docs site)
2020-11-06 16:10:08 +01:00
desc =>
?T("Path to the ODBC driver to use to connect to a Microsoft SQL "
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
"Server database. This option only applies if the _`sql_type`_ "
"option is set to 'mssql' and _`sql_server`_ is not an ODBC "
"connection string. The default value is: 'libtdsodbc.so'")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sql_password,
#{value => ?T("Password"),
desc =>
?T("The password for SQL authentication. The default is empty string.")}},
{sql_pool_size,
#{value => ?T("Size"),
desc =>
Improve wording of sql_pool_size option documentation (#2541)
2021-03-19 12:08:49 +01:00
?T("Number of connections to the SQL server that ejabberd will "
"open for each virtual host. The default value is 10. WARNING: "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"for SQLite this value is '1' by default and it's not recommended "
"to change it due to potential race conditions.")}},
{sql_port,
#{value => "1..65535",
desc =>
?T("The port where the SQL server is accepting connections. "
"The default is '3306' for MySQL, '5432' for PostgreSQL and "
Apply cosmetic changes from documentation
2021-01-08 18:34:38 +01:00
"'1433' for MS SQL. The option has no effect for SQLite.")}},
Document sql_prepared_statements
2020-04-01 21:01:47 +02:00
{sql_prepared_statements,
#{value => "true | false",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "added in 20.01",
Document sql_prepared_statements
2020-04-01 21:01:47 +02:00
desc =>
?T("This option is 'true' by default, and is useful to disable "
Mention in docs for sql_prepared_statements that it works with MySQL
2023-12-12 11:29:02 +01:00
"prepared statements. The option is valid for PostgreSQL and MySQL.")}},
Document sql_flags option introduced in 00c7600
2024-01-04 19:07:08 +01:00
{sql_flags,
#{value => "[mysql_alternative_upsert]",
Update version number from the unreleased 24.01 to 24.02
2024-02-24 17:40:03 +01:00
note => "added in 24.02",
Document sql_flags option introduced in 00c7600
2024-01-04 19:07:08 +01:00
desc =>
?T("This option accepts a list of SQL flags, and is empty by default. "
"'mysql_alternative_upsert' forces the alternative upsert implementation in MySQL.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sql_query_timeout,
#{value => "timeout()",
desc =>
?T("A time to wait for an SQL query response. "
"The default value is '60' seconds.")}},
{sql_queue_type,
#{value => "ram | file",
desc =>
?T("The type of a request queue for the SQL server. "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"See description of _`queue_type`_ option for the explanation. "
"The default value is the value defined in _`queue_type`_ "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"or 'ram' if the latter is not set.")}},
{sql_server,
Update p1_pgsql and mysql to support Unix Domain Socket (#3716)
2024-05-13 12:38:19 +02:00
#{value => "Host | IP Address | ODBC Connection String | Unix Socket Path",
Update version number of new commands, options and protocols to 24.06
2024-06-27 10:54:09 +02:00
note => "improved in 24.06",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
?T("The hostname or IP address of the SQL server. For _`sql_type`_ "
"'mssql' or 'odbc' this can also be an ODBC connection string. "
Update p1_pgsql and mysql to support Unix Domain Socket (#3716)
2024-05-13 12:38:19 +02:00
"When _`sql_type`_ is 'mysql' or 'pgsql', this can be the path to "
"a unix domain socket expressed like: \"unix:/path/to/socket\"."
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"The default value is 'localhost'.")}},
{sql_ssl,
#{value => "true | false",
Use the new 'note' field to annotate changes in 20.01..21.03
2021-05-05 11:43:49 +02:00
note => "improved in 20.03",
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
desc =>
?T("Whether to use SSL encrypted connections to the "
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
"SQL server. The option is only available for MySQL, MS SQL and "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"PostgreSQL. The default value is 'false'.")}},
{sql_ssl_cafile,
#{value => ?T("Path"),
desc =>
?T("A path to a file with CA root certificates that will "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"be used to verify SQL connections. Implies _`sql_ssl`_ "
"and _`sql_ssl_verify`_ options are set to 'true'. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"There is no default which means "
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
"certificate verification is disabled. "
"This option has no effect for MS SQL.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sql_ssl_certfile,
#{value => ?T("Path"),
desc =>
?T("A path to a certificate file that will be used "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"for SSL connections to the SQL server. Implies _`sql_ssl`_ "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"option is set to 'true'. There is no default which means "
"ejabberd won't provide a client certificate to the SQL "
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
"server. "
"This option has no effect for MS SQL.")}},
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
{sql_ssl_verify,
#{value => "true | false",
desc =>
?T("Whether to verify SSL connection to the SQL server against "
Use specific syntax so modules and top-level will be links If we use _`whatever`_ here in ejabberd man pages, it is converted to *`whatever`* in markdown, and docs.ejabberd.im/Makefile converts to the proper links
2021-08-21 18:31:21 +02:00
"CA root certificates defined in _`sql_ssl_cafile`_ option. "
"Implies _`sql_ssl`_ option is set to 'true'. "
Minor MS SQL improvements Support 'sql_ssl' option for MS SQL - set Encryption=required and Encrypt=yes in ODBC connection string to require SSL using default FreeTDS driver and Microsoft ODBC Driver for SQL Server repectively. Allow setting full ODBC connection string in 'sql_server' for MS SQL, allowing custom connection configuration beyond what is possible with just 'sql_odbc_driver' option.
2023-01-14 13:03:41 +01:00
"This option has no effect for MS SQL. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"The default value is 'false'.")}},
{sql_start_interval,
#{value => "timeout()",
desc =>
?T("A time to wait before retrying to restore failed SQL connection. "
"The default value is '30' seconds.")}},
{sql_username,
#{value => ?T("Username"),
desc =>
?T("A user name for SQL authentication. "
"The default value is 'ejabberd'.")}},
{trusted_proxies,
#{value => "all | [Network1, Network2, ...]",
desc =>
?T("Specify what proxies are trusted when an HTTP request "
"contains the header 'X-Forwarded-For'. You can specify "
"'all' to allow all proxies, or specify a list of IPs, "
"possibly with masks. The default value is an empty list. "
Rephrase sentences to avoid using "allow to + verb"
2024-01-11 13:23:45 +01:00
"Using this option you can know the real IP "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"of the request, for admin purpose, or security configuration "
"(for example using 'mod_fail2ban'). IMPORTANT: The proxy MUST "
"be configured to set the 'X-Forwarded-For' header if you "
"enable this option as, otherwise, the client can set it "
"itself and as a result the IP value cannot be trusted for "
"security rules in ejabberd.")}},
{validate_stream,
#{value => "true | false",
desc =>
?T("Whether to validate any incoming XML packet according "
"to the schemas of "
"https://github.com/processone/xmpp#supported-xmpp-elements"
"[supported XMPP extensions]. WARNING: the validation is only "
"intended for the use by client developers - don't enable "
"it in production environment. The default value is 'false'.")}},
{websocket_origin,
#{value => "ignore | URL",
desc =>
?T("This option enables validation for 'Origin' header to "
"protect against connections from other domains than given "
"in the configuration file. In this way, the lower layer load "
"balancer can be chosen for a specific ejabberd implementation "
Fix WebSocket uppercase
2022-02-11 15:22:14 +01:00
"while still providing a secure WebSocket connection. "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"The default value is 'ignore'. An example value of the 'URL' is "
"\"https://test.example.org:8081\".")}},
{websocket_ping_interval,
#{value => "timeout()",
desc =>
?T("Defines time between pings sent by the server to a client "
Fix WebSocket uppercase
2022-02-11 15:22:14 +01:00
"(WebSocket level protocol pings are used for this) to keep "
Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package).
2020-01-08 10:24:51 +01:00
"a connection active. If the client doesn't respond to two "
"consecutive pings, the connection will be assumed as closed. "
"The value of '0' can be used to disable the feature. This option "
"makes the server sending pings only for 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 '60' seconds.")}},
{websocket_timeout,
#{value => "timeout()",
desc =>
?T("Amount of time without any communication after which the "
"connection would be closed. The default value is '300' seconds.")}}].
%%%===================================================================
%%% Internal functions
%%%===================================================================
Copy Permalink