Chapril/xmpp.chapril.org-ejabberd
25
1
Fork 0
mirror of https://github.com/processone/ejabberd.git synced 2024-11-24 16:23:40 +01:00
Code Releases Activity

Add links in top-level options documentation to their Docs website sections

Browse Source
This commit is contained in:
Badlop 2024-08-12 12:43:30 +02:00
parent 918806006c
commit 15569d0b13
1 changed files with 78 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
src/ejabberd_options_doc.erl
View File

@ -30,8 +30,9 @@ doc() ->
[{hosts, [{hosts,
#{value => ?T("[Domain1, Domain2, ...]"), #{value => ?T("[Domain1, Domain2, ...]"),
desc => desc =>
?T("The option defines a list containing one or more " ?T("List of one or more "
"domains that 'ejabberd' will serve. This is a " "_`../configuration/basic.md#host-names|host names`_ "
"(or domains) that 'ejabberd' will serve. This is a "
"**mandatory** option.")}}, "**mandatory** option.")}},
{listen, {listen,
#{value => "[Options, ...]", #{value => "[Options, ...]",
@ -42,15 +43,15 @@ doc() ->
{modules, {modules,
#{value => "{Module: Options}", #{value => "{Module: Options}",
desc => desc =>
?T("The option for modules configuration. See " ?T("Set all the "
"_`modules.md|Modules`_ section " "_`modules.md|modules`_ configuration options.")}},
"for details.")}},
{loglevel, {loglevel,
#{value => #{value =>
"none | emergency | alert | critical | " "none | emergency | alert | critical | "
"error | warning | notice | info | debug", "error | warning | notice | info | debug",
desc => desc =>
?T("Verbosity of log files generated by ejabberd. " ?T("Verbosity of ejabberd "
"_`../configuration/basic.md#logging|logging`_. "
"The default value is 'info'. " "The default value is 'info'. "
"NOTE: previous versions of ejabberd had log levels " "NOTE: previous versions of ejabberd had log levels "
"defined in numeric format ('0..5'). The numeric values " "defined in numeric format ('0..5'). The numeric values "
@ -106,7 +107,8 @@ doc() ->
{default_db, {default_db,
#{value => "mnesia | sql", #{value => "mnesia | sql",
desc => desc =>
?T("Default persistent storage for ejabberd. " ?T("_`database.md#default-database|Default database`_ "
"to store persistent data in ejabberd. "
"Modules and other components (e.g. authentication) " "Modules and other components (e.g. authentication) "
"may have its own value. The default value is 'mnesia'.")}}, "may have its own value. The default value is 'mnesia'.")}},
{default_ram_db, {default_ram_db,
@ -135,7 +137,9 @@ doc() ->
{acl, {acl,
#{value => "{ACLName: {ACLType: ACLValue}}", #{value => "{ACLName: {ACLType: ACLValue}}",
desc => desc =>
?T("The option defines access control lists: named sets " ?T("This option defines "
"_`../configuration/basic.md#acl|access control lists`_: "
"named sets "
"of rules which are used to match against different targets " "of rules which are used to match against different targets "
"(such as a JID or an IP address). Every set of rules " "(such as a JID or an IP address). Every set of rules "
"has name 'ACLName': it can be any string except 'all' or 'none' " "has name 'ACLName': it can be any string except 'all' or 'none' "
@ -317,7 +321,9 @@ doc() ->
{anonymous_protocol, {anonymous_protocol,
#{value => "login_anon | sasl_anon | both", #{value => "login_anon | sasl_anon | both",
desc => desc =>
[?T("Define what anonymous protocol will be used: "), "", [?T("Define what "
"_`authentication.md#anonymous-login-and-sasl-anonymous|anonymous`_ "
"protocol will be used: "), "",
?T("* 'login_anon' means that the anonymous login method 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("* 'sasl_anon' means that the SASL Anonymous method will be used. "), "",
?T("* 'both' means that SASL Anonymous and login anonymous are both " ?T("* 'both' means that SASL Anonymous and login anonymous are both "
@ -332,10 +338,8 @@ doc() ->
{append_host_config, {append_host_config,
#{value => "{Host: Options}", #{value => "{Host: Options}",
desc => desc =>
?T("To define specific ejabberd modules in a virtual host, " ?T("Add a few specific options to a certain "
"you can define the global 'modules' option with the common modules, " "_`../configuration/basic.md#virtual-hosting|virtual host`_.")}},
"and later add specific modules to certain virtual hosts. "
"To accomplish that, 'append_host_config' option can be used.")}},
{auth_cache_life_time, {auth_cache_life_time,
#{value => "timeout()", #{value => "timeout()",
desc => desc =>
@ -354,7 +358,7 @@ doc() ->
{auth_method, {auth_method,
#{value => "[mnesia | sql | anonymous | external | jwt | ldap | pam, ...]", #{value => "[mnesia | sql | anonymous | external | jwt | ldap | pam, ...]",
desc => desc =>
?T("A list of authentication methods to use. " ?T("A list of _`authentication.md|authentication`_ methods to use. "
"If several methods are defined, authentication is " "If several methods are defined, authentication is "
"considered successful as long as authentication of " "considered successful as long as authentication of "
"at least one of the methods succeeds. " "at least one of the methods succeeds. "
@ -533,7 +537,9 @@ doc() ->
{define_macro, {define_macro,
#{value => "{MacroName: MacroValue}", #{value => "{MacroName: MacroValue}",
desc => desc =>
?T("Defines a macro. The value can be any valid arbitrary " ?T("Defines a "
"_`../configuration/file-format.md#macros-in-configuration-file|macro`_. "
"The value can be any valid arbitrary "
"YAML value. For convenience, it's recommended to define " "YAML value. For convenience, it's recommended to define "
"a 'MacroName' in capital letters. Duplicated macros are not allowed. " "a 'MacroName' in capital letters. Duplicated macros are not allowed. "
"Macros are processed after additional configuration files have " "Macros are processed after additional configuration files have "
@ -572,7 +578,9 @@ doc() ->
{domain_balancing, {domain_balancing,
#{value => "{Domain: Options}", #{value => "{Domain: Options}",
desc => desc =>
?T("An algorithm to load balance the components that are plugged " ?T("An algorithm to "
"_`../guide/clustering.md#service-load-balancing|load-balance`_ "
"the components that are plugged "
"on an ejabberd cluster. It means that you can plug one or several " "on an ejabberd cluster. It means that you can plug one or several "
"instances of the same component on each ejabberd node and that " "instances of the same component on each ejabberd node and that "
"the traffic will be automatically distributed. The algorithm " "the traffic will be automatically distributed. The algorithm "
@ -605,19 +613,23 @@ doc() ->
{extauth_pool_name, {extauth_pool_name,
#{value => ?T("Name"), #{value => ?T("Name"),
desc => desc =>
?T("Define the pool name appendix, so the full pool name will be " ?T("Define the pool name appendix in "
"_`authentication.md#external-script|external auth`_, "
"so the full pool name will be "
"'extauth_pool_Name'. The default value is the hostname.")}}, "'extauth_pool_Name'. The default value is the hostname.")}},
{extauth_pool_size, {extauth_pool_size,
#{value => ?T("Size"), #{value => ?T("Size"),
desc => desc =>
?T("The option defines the number of instances of the same " ?T("The option defines the number of instances of the same "
"external program to start for better load balancing. " "_`authentication.md#external-script|external auth`_ "
"program to start for better load balancing. "
"The default is the number of available CPU cores.")}}, "The default is the number of available CPU cores.")}},
{extauth_program, {extauth_program,
#{value => ?T("Path"), #{value => ?T("Path"),
desc => desc =>
?T("Indicate in this option the full path to the external " ?T("Indicate in this option the full path to the "
"authentication script. The script must be executable by ejabberd.")}}, "_`authentication.md#external-script|external authentication script`_. "
"The script must be executable by ejabberd.")}},
{ext_api_headers, {ext_api_headers,
#{value => "Headers", #{value => "Headers",
desc => desc =>
@ -655,8 +667,10 @@ doc() ->
{host_config, {host_config,
#{value => "{Host: Options}", #{value => "{Host: Options}",
desc => desc =>
?T("The option is used to redefine 'Options' for virtual host " ?T("The option is used to redefine 'Options' for "
"'Host'. In the example below LDAP authentication method " "_`../configuration/basic.md#virtual-hosting|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 'domain.tld' and SQL method "
"will be used on virtual host 'example.org'."), "will be used on virtual host 'example.org'."),
example => example =>
@ -674,7 +688,9 @@ doc() ->
{include_config_file, {include_config_file,
#{value => "[Filename, ...\\] | {Filename: Options}", #{value => "[Filename, ...\\] | {Filename: Options}",
desc => desc =>
?T("Read additional configuration from 'Filename'. If the " ?T("Read and "
"_`../configuration/file-format.md#include-additional-files|include additional file`_ "
"from 'Filename'. If the "
"value is provided in 'pass:[{Filename: Options}]' format, the " "value is provided in 'pass:[{Filename: Options}]' format, the "
"'Options' must be one of the following:")}, "'Options' must be one of the following:")},
[{disallow, [{disallow,
@ -701,7 +717,8 @@ doc() ->
{jwt_auth_only_rule, {jwt_auth_only_rule,
#{value => ?T("AccessName"), #{value => ?T("AccessName"),
desc => desc =>
?T("This ACL rule defines accounts that can use only this auth " ?T("This ACL rule defines accounts that can use only the "
"_`authentication.md#jwt-authentication|JWT`_ auth "
"method, even if others are also defined in the ejabberd " "method, even if others are also defined in the ejabberd "
"configuration file. In other words: if there are several auth " "configuration file. In other words: if there are several auth "
"methods enabled for this host (JWT, SQL, ...), users that " "methods enabled for this host (JWT, SQL, ...), users that "
@ -711,17 +728,22 @@ doc() ->
#{value => ?T("FieldName"), #{value => ?T("FieldName"),
desc => desc =>
?T("By default, the JID is defined in the '\"jid\"' JWT field. " ?T("By default, the JID is defined in the '\"jid\"' JWT field. "
"In this option you can specify other JWT field name " "In this option you can specify other "
"_`authentication.md#jwt-authentication|JWT`_ "
"field name "
"where the JID is defined.")}}, "where the JID is defined.")}},
{jwt_key, {jwt_key,
#{value => ?T("FilePath"), #{value => ?T("FilePath"),
desc => desc =>
?T("Path to the file that contains the JWK Key. " ?T("Path to the file that contains the "
"_`authentication.md#jwt-authentication|JWT`_ key. "
"The default value is 'undefined'.")}}, "The default value is 'undefined'.")}},
{language, {language,
#{value => ?T("Language"), #{value => ?T("Language"),
desc => desc =>
?T("The option defines the default language of server strings " ?T("Define the "
"_`../configuration/basic.md#default-language|default language`_ "
"of server strings "
"that can be seen by XMPP clients. If an XMPP client does not " "that can be seen by XMPP clients. If an XMPP client does not "
"possess 'xml:lang' attribute, the specified language is used. " "possess 'xml:lang' attribute, the specified language is used. "
"The default value is '\"en\"'. ")}}, "The default value is '\"en\"'. ")}},
@ -909,7 +931,9 @@ doc() ->
{new_sql_schema, {new_sql_schema,
#{value => "true | false", #{value => "true | false",
desc => desc =>
{?T("Whether to use 'new' SQL schema. All schemas are located " {?T("Whether to use the "
"_`database.md#default-and-new-schemas|new SQL schema`_. "
"All schemas are located "
"at <https://github.com/processone/ejabberd/tree/~s/sql>. " "at <https://github.com/processone/ejabberd/tree/~s/sql>. "
"There are two schemas available. The default legacy schema " "There are two schemas available. The default legacy schema "
"stores one XMPP domain into one ejabberd database. " "stores one XMPP domain into one ejabberd database. "
@ -1049,14 +1073,18 @@ doc() ->
{pam_service, {pam_service,
#{value => ?T("Name"), #{value => ?T("Name"),
desc => desc =>
?T("This option defines the PAM service name. Refer to the PAM " ?T("This option defines the "
"_`authentication.md#pam-authentication|PAM`_ "
"service name. Refer to the PAM "
"documentation of your operation system for more information. " "documentation of your operation system for more information. "
"The default value is 'ejabberd'.")}}, "The default value is 'ejabberd'.")}},
{pam_userinfotype, {pam_userinfotype,
#{value => "username | jid", #{value => "username | jid",
desc => desc =>
?T("This option defines what type of information about the " ?T("This option defines what type of information about the "
"user ejabberd provides to the PAM service: only the username, " "user ejabberd provides to the "
"_`authentication.md#pam-authentication|PAM`_ "
"service: only the username, "
"or the user's JID. Default is 'username'.")}}, "or the user's JID. Default is 'username'.")}},
{pgsql_users_number_estimate, {pgsql_users_number_estimate,
#{value => "true | false", #{value => "true | false",
@ -1073,36 +1101,42 @@ doc() ->
#{value => "timeout()", #{value => "timeout()",
desc => desc =>
?T("A timeout to wait for the connection to be re-established " ?T("A timeout to wait for the connection to be re-established "
"to the Redis server. The default is '1 second'.")}}, "to the _`database.md#redis|Redis`_ "
"server. The default is '1 second'.")}},
{redis_db, {redis_db,
#{value => ?T("Number"), #{value => ?T("Number"),
desc => ?T("Redis database number. The default is '0'.")}}, desc => ?T("_`database.md#redis|Redis`_ "
"database number. The default is '0'.")}},
{redis_password, {redis_password,
#{value => ?T("Password"), #{value => ?T("Password"),
desc => desc =>
?T("The password to the Redis server. " ?T("The password to the _`database.md#redis|Redis`_ server. "
"The default is an empty string, i.e. no password.")}}, "The default is an empty string, i.e. no password.")}},
{redis_pool_size, {redis_pool_size,
#{value => ?T("Number"), #{value => ?T("Number"),
desc => desc =>
?T("The number of simultaneous connections to the Redis server. " ?T("The number of simultaneous connections to the "
"_`database.md#redis|Redis`_ server. "
"The default value is '10'.")}}, "The default value is '10'.")}},
{redis_port, {redis_port,
#{value => "1..65535", #{value => "1..65535",
desc => desc =>
?T("The port where the Redis server is accepting connections. " ?T("The port where the _`database.md#redis|Redis`_ "
" server is accepting connections. "
"The default is '6379'.")}}, "The default is '6379'.")}},
{redis_queue_type, {redis_queue_type,
#{value => "ram | file", #{value => "ram | file",
desc => desc =>
?T("The type of request queue for the Redis server. " ?T("The type of request queue for the "
"_`database.md#redis|Redis`_ server. "
"See description of _`queue_type`_ option for the explanation. " "See description of _`queue_type`_ option for the explanation. "
"The default value is the value defined in _`queue_type`_ " "The default value is the value defined in _`queue_type`_ "
"or 'ram' if the latter is not set.")}}, "or 'ram' if the latter is not set.")}},
{redis_server, {redis_server,
#{value => ?T("Hostname"), #{value => ?T("Hostname"),
desc => desc =>
?T("A hostname or an IP address of the Redis server. " ?T("A hostname or an IP address of the "
"_`database.md#redis|Redis`_ server."
"The default is 'localhost'.")}}, "The default is 'localhost'.")}},
{registration_timeout, {registration_timeout,
#{value => "timeout()", #{value => "timeout()",
@ -1257,7 +1291,9 @@ doc() ->
{shaper, {shaper,
#{value => "{ShaperName: Rate}", #{value => "{ShaperName: Rate}",
desc => desc =>
?T("The option defines a set of shapers. Every shaper is assigned " ?T("The option defines a set of "
"_`../configuration/basic.md#shapers|shapers`_. "
"Every shaper is assigned "
"a name 'ShaperName' that can be used in other parts of the " "a name 'ShaperName' that can be used in other parts of the "
"configuration file, such as _`shaper_rules`_ option. The shaper " "configuration file, such as _`shaper_rules`_ option. The shaper "
"itself is defined by its 'Rate', where 'Rate' stands for the " "itself is defined by its 'Rate', where 'Rate' stands for the "
@ -1274,7 +1310,9 @@ doc() ->
{shaper_rules, {shaper_rules,
#{value => "{ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}", #{value => "{ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}",
desc => desc =>
?T("An entry allowing to declaring shaper to use for matching user/hosts. " ?T("This option defines "
"_`../configuration/basic.md#shaper-rules|shaper rules`_ "
"to use for matching user/hosts. "
"Semantics is similar to _`access_rules`_ option, the only difference is " "Semantics is similar to _`access_rules`_ option, the only difference is "
"that instead using 'allow' or 'deny', a name of a shaper (defined in " "that instead using 'allow' or 'deny', a name of a shaper (defined in "
"_`shaper`_ option) or a positive number should be used."), "_`shaper`_ option) or a positive number should be used."),