Chapril
/
xmpp.chapril.org-ejabberd
mirror of https://github.com/processone/ejabberd.git
24
1
Fork 0
Code Releases Activity

Add mod_pubsub configuration documentation

This commit is contained in:
Badlop 2020-01-13 13:25:08 +01:00
parent ccb47a67c4
commit 5ee2f48aea
1 changed files with 202 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
src/mod_pubsub.erl
View File

@ -90,7 +90,7 @@
%% API and gen_server callbacks
-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]).
-export([route/1]).
@ -4180,3 +4180,204 @@ mod_options(Host) ->
{max_subscriptions_node, undefined},
{default_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",
" ..."
]}
]}.