Add mod_pubsub configuration documentation
This commit is contained in:
parent
ccb47a67c4
commit
5ee2f48aea
|
@ -90,7 +90,7 @@
|
||||||
|
|
||||||
%% API and gen_server callbacks
|
%% API and gen_server callbacks
|
||||||
-export([start/2, stop/1, init/1,
|
-export([start/2, stop/1, init/1,
|
||||||
handle_call/3, handle_cast/2, handle_info/2,
|
handle_call/3, handle_cast/2, handle_info/2, mod_doc/0,
|
||||||
terminate/2, code_change/3, depends/2, mod_opt_type/1, mod_options/1]).
|
terminate/2, code_change/3, depends/2, mod_opt_type/1, mod_options/1]).
|
||||||
|
|
||||||
-export([route/1]).
|
-export([route/1]).
|
||||||
|
@ -4180,3 +4180,204 @@ mod_options(Host) ->
|
||||||
{max_subscriptions_node, undefined},
|
{max_subscriptions_node, undefined},
|
||||||
{default_node_config, []},
|
{default_node_config, []},
|
||||||
{force_node_config, []}].
|
{force_node_config, []}].
|
||||||
|
|
||||||
|
mod_doc() ->
|
||||||
|
#{desc =>
|
||||||
|
[?T("This module offers a service for "
|
||||||
|
"https://xmpp.org/extensions/xep-0060.html"
|
||||||
|
"[XEP-0060: Publish-Subscribe]. The functionality in "
|
||||||
|
"'mod_pubsub' can be extended using plugins. "
|
||||||
|
"The plugin that implements PEP "
|
||||||
|
"(https://xmpp.org/extensions/xep-0163.html"
|
||||||
|
"[XEP-0163: Personal Eventing via Pubsub]) "
|
||||||
|
"is enabled in the default ejabberd configuration file, "
|
||||||
|
"and it requires 'mod_caps'.")],
|
||||||
|
opts =>
|
||||||
|
[{max_nodes_discoitems,
|
||||||
|
#{value => "pos_integer() | infinity",
|
||||||
|
desc => ?T("The maximum number of nodes to return in a "
|
||||||
|
"discoitem response. The default value is: '100'.")}},
|
||||||
|
{access_createnode,
|
||||||
|
#{value => "AccessName",
|
||||||
|
desc => ?T("This option restricts which users are allowed to "
|
||||||
|
"create pubsub nodes using 'acl' and 'access'. "
|
||||||
|
"By default any account in the local ejabberd server "
|
||||||
|
"is allowed to create pubsub nodes. "
|
||||||
|
"The default value is: 'all'.")}},
|
||||||
|
{max_items_node,
|
||||||
|
#{value => "MaxItems",
|
||||||
|
desc => ?T("Define the maximum number of items that can be "
|
||||||
|
"stored in a node. Default value is: '10'.")}},
|
||||||
|
{max_subscriptions_node,
|
||||||
|
#{value => "MaxSubs",
|
||||||
|
desc => ?T("Define the maximum number of subscriptions managed "
|
||||||
|
"by a node. "
|
||||||
|
"Default value is no limitation: 'undefined'.")}},
|
||||||
|
{plugins,
|
||||||
|
#{value => "[Plugin, ...]",
|
||||||
|
desc => [?T("To specify which pubsub node plugins to use. "
|
||||||
|
"The first one in the list is used by default. "
|
||||||
|
"If this option is not defined, the default plugins "
|
||||||
|
"list is: '[flat]'. PubSub clients can define which "
|
||||||
|
"plugin to use when creating a node: "
|
||||||
|
"add 'type=\'plugin-name\'' attribute "
|
||||||
|
"to the 'create' stanza element."),
|
||||||
|
?T("- 'flat' plugin handles the default behaviour and "
|
||||||
|
"follows standard XEP-0060 implementation."),
|
||||||
|
?T("- 'pep' plugin adds extention to handle Personal "
|
||||||
|
"Eventing Protocol (XEP-0163) to the PubSub engine. "
|
||||||
|
"Adding pep allows to handle PEP automatically.")]}},
|
||||||
|
{nodetree,
|
||||||
|
#{value => "Nodetree",
|
||||||
|
desc =>
|
||||||
|
[?T("To specify which nodetree to use. If not defined, the "
|
||||||
|
"default pubsub nodetree is used: 'tree'. Only one "
|
||||||
|
"nodetree can be used per host, and is shared by all "
|
||||||
|
"node plugins."),
|
||||||
|
?T("- 'tree' nodetree store node configuration and "
|
||||||
|
"relations on the database. 'flat' nodes are stored "
|
||||||
|
"without any relationship, and 'hometree' nodes can "
|
||||||
|
"have child nodes."),
|
||||||
|
?T("- 'virtual' nodetree does not store nodes on database. "
|
||||||
|
"This saves resources on systems with tons of nodes. "
|
||||||
|
"If using the 'virtual' nodetree, you can only enable "
|
||||||
|
"those node plugins: '[flat, pep]' or '[flat]'; any "
|
||||||
|
"other plugins configuration will not work. Also, all "
|
||||||
|
"nodes will have the default configuration, and this "
|
||||||
|
"can not be changed. Using 'virtual' nodetree requires "
|
||||||
|
"to start from a clean database, it will not work if "
|
||||||
|
"you used the default 'tree' nodetree before."),
|
||||||
|
?T("- 'dag' nodetree provides experimental support for "
|
||||||
|
"PubSub Collection Nodes (XEP-0248). In that case you "
|
||||||
|
"should also add 'dag' node plugin as default, for "
|
||||||
|
"example: 'plugins: [flat,pep]'")]}},
|
||||||
|
{ignore_pep_from_offline,
|
||||||
|
#{value => "false | true",
|
||||||
|
desc => ?T("To specify whether or not we should get last "
|
||||||
|
"published PEP items from users in our roster which "
|
||||||
|
"are offline when we connect. Value is 'true' or "
|
||||||
|
"'false'. If not defined, pubsub assumes true so we "
|
||||||
|
"only get last items of online contacts.")}},
|
||||||
|
{last_item_cache,
|
||||||
|
#{value => "false | true",
|
||||||
|
desc => ?T("To specify whether or not pubsub should cache last "
|
||||||
|
"items. Value is 'true' or 'false'. If not defined, "
|
||||||
|
"pubsub does not cache last items. On systems with not"
|
||||||
|
" so many nodes, caching last items speeds up pubsub "
|
||||||
|
"and allows to raise user connection rate. The cost "
|
||||||
|
"is memory usage, as every item is stored in memory.")}},
|
||||||
|
{force_node_config,
|
||||||
|
#{value => "List of Node and the list of its Key:Value",
|
||||||
|
desc => ?T("Define the configuration for given nodes. "
|
||||||
|
"The default value is: '[]'."),
|
||||||
|
example =>
|
||||||
|
["force_node_config:",
|
||||||
|
" ## Avoid buggy clients to make their bookmarks public",
|
||||||
|
" storage:bookmarks:",
|
||||||
|
" access_model: whitelist"]}},
|
||||||
|
{default_node_config,
|
||||||
|
#{value => "List of Key:Value",
|
||||||
|
desc => ?T("To override default node configuration, regardless "
|
||||||
|
"of node plugin. Value is a list of key-value "
|
||||||
|
"definition. Node configuration still uses default "
|
||||||
|
"configuration defined by node plugin, and overrides "
|
||||||
|
"any items by value defined in this configurable list.
|
||||||
|
")}},
|
||||||
|
{pep_mapping,
|
||||||
|
#{value => "List of Key:Value",
|
||||||
|
desc => ?T("This allows to define a list of key-value to choose "
|
||||||
|
"defined node plugins on given PEP namespace."),
|
||||||
|
example =>
|
||||||
|
[{?T("The following example will use 'node_tune' instead of "
|
||||||
|
"'node_pep' for every PEP node with the tune namespace:"),
|
||||||
|
["modules:",
|
||||||
|
" ...",
|
||||||
|
" mod_pubsub:",
|
||||||
|
" pep_mapping:",
|
||||||
|
" http://jabber.org/protocol/tune: tune",
|
||||||
|
" ..."]
|
||||||
|
}]}},
|
||||||
|
{db_type,
|
||||||
|
#{value => "mnesia | sql",
|
||||||
|
desc =>
|
||||||
|
?T("Same as top-level 'default_db' option, but applied to "
|
||||||
|
"this module only.")}},
|
||||||
|
{host,
|
||||||
|
#{desc => ?T("Deprecated. Use 'hosts' instead.")}},
|
||||||
|
{hosts,
|
||||||
|
#{value => ?T("[Host, ...]"),
|
||||||
|
desc =>
|
||||||
|
?T("This option defines the Jabber IDs of the service. "
|
||||||
|
"If the 'hosts' option is not specified, the only Jabber "
|
||||||
|
"ID will be the hostname of the virtual host with the "
|
||||||
|
"prefix \"vjud.\". The keyword '@HOST@' is replaced with "
|
||||||
|
"the real virtual host name.")}},
|
||||||
|
{name,
|
||||||
|
#{value => ?T("Name"),
|
||||||
|
desc =>
|
||||||
|
?T("The value of the service name. This name is only visible "
|
||||||
|
"in some clients that support "
|
||||||
|
"https://xmpp.org/extensions/xep-0030.html"
|
||||||
|
"[XEP-0030: Service Discovery]. "
|
||||||
|
"The default is 'vCard User Search'.")}},
|
||||||
|
{vcard,
|
||||||
|
#{value => ?T("vCard"),
|
||||||
|
desc =>
|
||||||
|
?T("A custom vCard of the server that will be displayed by "
|
||||||
|
"some XMPP clients in Service Discovery. The value of "
|
||||||
|
"'vCard' is a YAML map constructed from an XML "
|
||||||
|
"representation of vCard. Since the representation has "
|
||||||
|
"no attributes, the mapping is straightforward."),
|
||||||
|
example =>
|
||||||
|
[{?T("The following XML representation of vCard:"),
|
||||||
|
["<vCard xmlns='vcard-temp'>",
|
||||||
|
" <FN>PubSub Service</FN>",
|
||||||
|
" <ADR>",
|
||||||
|
" <WORK/>",
|
||||||
|
" <STREET>Elm Street</STREET>",
|
||||||
|
" </ADR>",
|
||||||
|
"</vCard>"]},
|
||||||
|
{?T("will be translated to:"),
|
||||||
|
["vcard:",
|
||||||
|
" fn: PubSub Service",
|
||||||
|
" adr:",
|
||||||
|
" -",
|
||||||
|
" work: true",
|
||||||
|
" street: Elm Street"]}]}}
|
||||||
|
],
|
||||||
|
example =>
|
||||||
|
[{?T("Example of configuration that uses flat nodes as default, "
|
||||||
|
"and allows use of flat, hometree and pep nodes:"),
|
||||||
|
[
|
||||||
|
"modules:",
|
||||||
|
" ...",
|
||||||
|
" mod_pubsub:",
|
||||||
|
" access_createnode: pubsub_createnode",
|
||||||
|
" max_subscriptions_node: 100",
|
||||||
|
" default_node_config:",
|
||||||
|
" notification_type: normal",
|
||||||
|
" notify_retract: false",
|
||||||
|
" max_items: 4",
|
||||||
|
" plugins:",
|
||||||
|
" - flat",
|
||||||
|
" - pep",
|
||||||
|
" ..."
|
||||||
|
]},
|
||||||
|
{?T("Using relational database requires using mod_pubsub with "
|
||||||
|
"db_type 'sql'. Only flat, hometree and pep plugins supports "
|
||||||
|
"SQL. The following example shows previous configuration "
|
||||||
|
"with SQL usage:"),
|
||||||
|
[
|
||||||
|
"modules:",
|
||||||
|
" ...",
|
||||||
|
" mod_pubsub:",
|
||||||
|
" db_type: sql",
|
||||||
|
" access_createnode: pubsub_createnode",
|
||||||
|
" ignore_pep_from_offline: true",
|
||||||
|
" last_item_cache: false",
|
||||||
|
" plugins:",
|
||||||
|
" - flat",
|
||||||
|
" - pep",
|
||||||
|
" ..."
|
||||||
|
]}
|
||||||
|
]}.
|
||||||
|
|
Loading…
Reference in New Issue