diff --git a/src/ejabberd_options_doc.erl b/src/ejabberd_options_doc.erl index 2d201a471..5494cc12c 100644 --- a/src/ejabberd_options_doc.erl +++ b/src/ejabberd_options_doc.erl @@ -60,32 +60,49 @@ doc() -> #{value => "timeout()", desc => ?T("The time of a cached item to keep in cache. " - "Once it's expired, the corresponding item is " - "erased from cache. The default value is 'one hour'.")}}, + "Once it's expired, the corresponding item is " + "erased from cache. The default value is 'one hour'. " + "Several modules have a similar option; and some core " + "ejabberd parts support similar options too, see " + "'auth_cache_life_time', 'oauth_cache_life_time', " + "'router_cache_life_time', and 'sm_cache_life_time'.")}}, {cache_missed, #{value => "true | false", desc => ?T("Whether or not to cache missed lookups. When there is " - "an attempt to lookup for a value in a database and " - "this value is not found and the option is set to 'true', " - "this attempt will be cached and no attempts will be " - "performed until the cache expires (see 'cache_life_time'). " - "Usually you don't want to change it. Default is 'true'.")}}, + "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 " + "performed until the cache expires (see 'cache_life_time'). " + "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 " + "'auth_cache_missed', 'oauth_cache_missed', " + "'router_cache_missed', and 'sm_cache_missed'.")}}, {cache_size, #{value => "pos_integer() | infinity", desc => - ?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'.")}}, + ?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 " + "'auth_cache_size', 'oauth_cache_size', " + "'router_cache_size', and 'sm_cache_size'.")}}, {use_cache, #{value => "true | false", - desc => ?T("Enable or disable cache. The default is 'true'.")}}, + 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 " + "'auth_use_cache', 'oauth_use_cache', 'router_use_cache', " + "and 'sm_use_cache'.")}}, {default_db, #{value => "mnesia | sql", desc => diff --git a/src/mod_announce.erl b/src/mod_announce.erl index cc4d20c83..a0bfa180b 100644 --- a/src/mod_announce.erl +++ b/src/mod_announce.erl @@ -925,6 +925,10 @@ mod_doc() -> "Configured users can perform these actions with an XMPP " "client either using Ad-hoc Commands or sending messages " "to specific JIDs."), "", + ?T("Note that this module can be resource intensive on large " + "deployments as it may broadcast a lot of messages. This module " + "should be disabled for instances of ejabberd with hundreds of " + "thousands users."), "", ?T("The Ad-hoc Commands are listed in the Server Discovery. " "For this feature to work, 'mod_adhoc' must be enabled."), "", ?T("The specific JIDs where messages can be sent are listed below. " diff --git a/src/mod_delegation.erl b/src/mod_delegation.erl index ea0061089..da16ce89e 100644 --- a/src/mod_delegation.erl +++ b/src/mod_delegation.erl @@ -85,13 +85,18 @@ mod_options(_Host) -> mod_doc() -> #{desc => - ?T("This module is an implementation of " + [?T("This module is an implementation of " "https://xmpp.org/extensions/xep-0355.html" "[XEP-0355: Namespace Delegation]. " "Only admin mode has been implemented by now. " "Namespace delegation allows external services to " "handle IQ using specific namespace. This may be applied " - "for external PEP service."), + "for external PEP service."), "", + ?T("WARNING: Security issue: Namespace delegation gives components " + "access to sensitive data, so permission should be granted " + "carefully, only if you trust the component."), "", + ?T("NOTE: This module is complementary to 'mod_privilege' but can " + "also be used separately.")], opts => [{namespaces, #{value => "{Namespace: Options}", @@ -109,6 +114,10 @@ mod_doc() -> ?T("The option defines which components are allowed " "for namespace delegation. The default value is 'none'.")}}]}], example => + [{?T("Make sure you do not delegate the same namespace to several " + "services at the same time. As in the example provided later, " + "to have the 'sat-pubsub.example.org' component perform " + "correctly disable the 'mod_pubsub' module."), ["access_rules:", " external_pubsub:", " allow: external_component", @@ -126,7 +135,7 @@ mod_doc() -> " urn:xmpp:mam:1:", " access: external_mam", " http://jabber.org/protocol/pubsub:", - " access: external_pubsub"]}. + " access: external_pubsub"]}]}. depends(_, _) -> []. diff --git a/src/mod_fail2ban.erl b/src/mod_fail2ban.erl index b9fed0db0..48e7fb8e0 100644 --- a/src/mod_fail2ban.erl +++ b/src/mod_fail2ban.erl @@ -263,7 +263,13 @@ mod_doc() -> "record of authentication failures after some time since the " "first failure or on a successful authentication. " "It also does not simply block network traffic, but " - "provides the client with a descriptive error message.")], + "provides the client with a descriptive error message."), "", + ?T("WARNING: You should not use this module behind a proxy or load " + "balancer. ejabberd will see the failures as coming from the " + "load balancer and, when the threshold of auth failures is " + "reached, will reject all connections coming from the load " + "balancer. You can lock all your user base out of ejabberd " + "when using this module behind a proxy.")], opts => [{access, #{value => ?T("AccessName"), diff --git a/src/mod_http_api.erl b/src/mod_http_api.erl index 912299e45..3a1b22034 100644 --- a/src/mod_http_api.erl +++ b/src/mod_http_api.erl @@ -524,5 +524,13 @@ mod_options(_) -> mod_doc() -> #{desc => - ?T("This module provides a ReST API to call " - "ejabberd commands using JSON data.")}. + [?T("This module provides a ReST API to call ejabberd commands " + "using JSON data."), "", + ?T("To use this module, in addition to adding it to the 'modules' " + "section, you must also add it to 'request_handlers' of some " + "listener."), "", + ?T("To use a specific API version N, when defining the URL path " + "in the request_handlers, add a 'vN'. " + "For example: '/api/v2: mod_http_api'"), "", + ?T("To run a command, send a POST request to the corresponding " + "URL: 'http://localhost:5280/api/'")]}. diff --git a/src/mod_http_upload_quota.erl b/src/mod_http_upload_quota.erl index ed1bbe331..2fd7b5c28 100644 --- a/src/mod_http_upload_quota.erl +++ b/src/mod_http_upload_quota.erl @@ -130,6 +130,10 @@ mod_doc() -> "the specified soft quota (see 'access_soft_quota'). " "The default value is 'hard_upload_quota'.")}}], example => + [{?T("Please note that it's not necessary to specify the " + "'access_hard_quota' and 'access_soft_quota' options in order " + "to use the quota feature. You can stick to the default names " + "and just specify access rules such as those in this example:"), ["shaper_rules:", " ...", " soft_upload_quota:", @@ -143,7 +147,7 @@ mod_doc() -> " mod_http_upload: {}", " mod_http_upload_quota:", " max_days: 100", - " ..."]}. + " ..."]}]}. -spec depends(binary(), gen_mod:opts()) -> [{module(), hard | soft}]. depends(_Host, _Opts) -> diff --git a/src/mod_mix.erl b/src/mod_mix.erl index bc69c1aa1..29fa6e4ac 100644 --- a/src/mod_mix.erl +++ b/src/mod_mix.erl @@ -107,6 +107,10 @@ mod_doc() -> "yet ready to use in production. It's asserted that " "the MIX protocol is going to replace the MUC protocol " "in the future (see 'mod_muc')."), "", + ?T("To learn more about how to use that feature, you can refer to " + "our tutorial: https://docs.ejabberd.im/tutorials/mix-010/" + "[Getting started with XEP-0369: Mediated Information " + "eXchange (MIX) v0.1]."), "", ?T("The module depends on 'mod_mam'.")], opts => [{access_create, diff --git a/src/mod_muc.erl b/src/mod_muc.erl index 65f70d1d6..59ea3190a 100644 --- a/src/mod_muc.erl +++ b/src/mod_muc.erl @@ -1280,9 +1280,20 @@ mod_options(Host) -> mod_doc() -> #{desc => - ?T("This module provides support for https://xmpp.org/extensions/xep-0045.html" + [?T("This module provides support for https://xmpp.org/extensions/xep-0045.html" "[XEP-0045: Multi-User Chat]. Users can discover existing rooms, " - "join or create them. Occupants of a room can chat in public or have private chats."), + "join or create them. Occupants of a room can chat in public or have private chats."), "", + ?T("The MUC service allows any Jabber ID to register a nickname, so " + "nobody else can use that nickname in any room in the MUC " + "service. To register a nickname, open the Service Discovery in " + "your XMPP client and register in the MUC service."), "", + ?T("This module supports clustering and load balancing. One module " + "can be started per cluster node. Rooms are distributed at " + "creation time on all available MUC module instances. The " + "multi-user chat module is clustered but the rooms themselves " + "are not clustered nor fault-tolerant: if the node managing a " + "set of rooms goes down, the rooms disappear and they will be " + "recreated on an available node on first connection attempt.")], opts => [{access, #{value => ?T("AccessName"), diff --git a/src/mod_privilege.erl b/src/mod_privilege.erl index c334348b4..1830cb5ab 100644 --- a/src/mod_privilege.erl +++ b/src/mod_privilege.erl @@ -100,6 +100,12 @@ mod_doc() -> "It is worth noting that the permissions grant access to " "the component to a specific data type for all users of " "the virtual host on which 'mod_privilege' is loaded."), "", + ?T("Make sure you have a listener configured to connect your " + "component. Check the section about listening ports for more " + "information."), "", + ?T("WARNING: Security issue: Privileged access gives components " + "access to sensitive data, so permission should be granted " + "carefully, only if you trust a component."), "", ?T("NOTE: This module is complementary to 'mod_delegation', " "but can also be used separately.")], opts => diff --git a/src/mod_register.erl b/src/mod_register.erl index ac0e667ea..349113191 100644 --- a/src/mod_register.erl +++ b/src/mod_register.erl @@ -628,7 +628,10 @@ mod_doc() -> "This protocol enables end users to use a XMPP client to:"), "", ?T("* Register a new account on the server."), "", ?T("* Change the password from an existing account on the server."), "", - ?T("* Delete an existing account on the server.")], + ?T("* Delete an existing account on the server."), "", + ?T("This module reads also another option defined globally for the " + "server: 'registration_timeout'. Please check that option " + "documentation in the section with top-level options.")], opts => [{access, #{value => ?T("AccessName"), diff --git a/src/mod_register_web.erl b/src/mod_register_web.erl index a2249430c..15eb58e75 100644 --- a/src/mod_register_web.erl +++ b/src/mod_register_web.erl @@ -625,5 +625,13 @@ mod_doc() -> ?T("- Register a new account on the server."), "", ?T("- Change the password from an existing account on the server."), "", ?T("- Delete an existing account on the server."), "", + ?T("This module supports CAPTCHA image to register a new account. " + "To enable this feature, configure the options 'captcha\_cmd' " + "and 'captcha\_host', which are documented in the section with " + "top-level options."), "", + ?T("As an example usage, the users of the host 'example.org' can " + "visit the page: 'https://example.org:5281/register/' It is " + "important to include the last / character in the URL, " + "otherwise the subpages URL will be incorrect."), "", ?T("The module depends on 'mod_register' where all the configuration " "is performed.")]}. diff --git a/src/mod_shared_roster_ldap.erl b/src/mod_shared_roster_ldap.erl index f8594af71..80297b41b 100644 --- a/src/mod_shared_roster_ldap.erl +++ b/src/mod_shared_roster_ldap.erl @@ -654,10 +654,12 @@ mod_doc() -> ?T("- Connection parameters: The module also accepts the " "connection parameters, all of which default to the top-level " "parameter of the same name, if unspecified. " - "See 'LDAP Connection' for more information about them."), "", - ?T("The ejabberd Guide includes details for retrieving the roster, " - "configuration examples including Flat DIT and Deep DIT, and " - "also describes some of those options in more detail.")], + "See http://../database-ldap/#ldap-connection[LDAP Connection] " + "section for more information about them."), "", + ?T("Check also the http://../database-ldap/#configuration-examples" + "[Configuration examples] section to get details about " + "retrieving the roster, " + "and configuration examples including Flat DIT and Deep DIT.")], opts => [ %% Filters: @@ -683,12 +685,14 @@ mod_doc() -> ?T("\"User Filter\", used for retrieving the human-readable " "name of roster entries (usually full names of people in " "the roster). See also the parameters 'ldap_userdesc' and " - "'ldap_useruid'. For details check the ejabberd Guide.")}}, + "'ldap_useruid'. For more information check the LDAP " + "http://../database-ldap/#filters[Filters] section.")}}, {ldap_filter, #{desc => ?T("Additional filter which is AND-ed together " "with \"User Filter\" and \"Group Filter\". " - "For details please read the ejabberd Guide.")}}, + "For more information check the LDAP " + "http://../database-ldap/#filters[Filters] section.")}}, %% Attributes: {ldap_groupattr, #{desc => @@ -739,17 +743,16 @@ mod_doc() -> {ldap_memberattr_format_re, #{desc => ?T("A regex for extracting user ID from the value of the " - "attribute named by 'ldap_memberattr'. For details " - "please read the ejabberd Guide.")}}, + "attribute named by 'ldap_memberattr'. Check the LDAP " + "http://../database-ldap/#control-parameters" + "[Control Parameters] section.")}}, {ldap_auth_check, #{value => "true | false", desc => ?T("Whether the module should check (via the ejabberd " "authentication subsystem) for existence of each user in " - "the shared LDAP roster. See section " - "'mod_shared_roster_ldap' for more information. Set to " - "'false' if you want to disable the check. " - "Default value is 'true'.")}}] ++ + "the shared LDAP roster. Set to 'false' if you want to " + "disable the check. Default value is 'true'.")}}] ++ [{Opt, #{desc => {?T("Same as top-level '~s' option, but "