Mercurial > prosody-modules

comparison mod_delegation/README.md @ 5975:fe081789f7b5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parents mod_delegation/README.markdown@679f1834dbdb
children
comparison
equal deleted inserted replaced
5974:5a65a632d5b9 5975:fe081789f7b5
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: 'XEP-0355 (Namespace Delegation) implementation'
5 ...
6
7 Introduction
8 ============
9
10 Namespace Delegation is an extension which allows server to delegate some
11 features handling to an entity/component. Typical use case is an external PEP
12 service, but it can be used more generally when your preferred server lack one
13 internal feature, and you found an external component which can do it.
14
15 Details
16 =======
17
18 You can have all the details by reading the
19 [XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin mode is
20 implemented so far.
21
22 Usage
23 =====
24
25 To use the module, like usual add **"delegation"** to your *modules\_enabled*.
26 Note that if you use it with a local component, you also need to activate the
27 module in your component section:
28
29 modules_enabled = {
30 [...]
31
32 "delegation";
33 }
34
35 [...]
36
37 Component "youcomponent.yourdomain.tld"
38 component_secret = "yourpassword"
39 modules_enabled = {"delegation"}
40
41 then specify delegated namespaces **in your host section** like that:
42
43 VirtualHost "yourdomain.tld"
44
45 delegations = {
46 ["urn:xmpp:mam:2"] = {
47 filtering = {"node"};
48 jid = "pubsub.yourdomain.tld";
49 },
50 ["http://jabber.org/protocol/pubsub"] = {
51 jid = "pubsub.yourdomain.tld";
52 },
53 ["http://jabber.org/protocol/pubsub#owner"] = {
54 jid = "pubsub.yourdomain.tld";
55 },
56 ["urn:xmpp:delegation:2:bare:disco#info:*"] = {
57 jid = "pubsub.yourdomain.tld";
58 },
59 ["urn:xmpp:delegation:2:bare:disco#items:*"] = {
60 jid = "pubsub.yourdomain.tld";
61 },
62
63 }
64
65 Here all MAM requests with a "node" attribute (i.e. all MAM pubsub request) will
66 be delegated to pubsub.yourdomain.tld. Similarly, all pubsub request to the host
67 (i.e. the PEP requests) will be delegated to pubsub.yourdomain.tld. Check the
68 XEP for the meaning of "urn:xmpp:delegation:2:bare:disco#info:*" and
69 "urn:xmpp:delegation:2:bare:disco#items:*".
70
71 **/!\ Be extra careful when you give a delegation to an entity/component, it's a
72 powerful access, only do it if you absolutely trust the component/entity, and
73 you know where the software is coming from**
74
75 Configuration
76 =============
77
78 The configuration is done with a table which map delegated namespace to
79 namespace data. Namespace data MUST have a **jid** (in the form **jid =
80 "delegated@domain.tld"**) and MAY have an additional **filtering** array. If
81 filtering is present, request with attributes in the array will be delegated,
82 others will be treated normally (i.e. by Prosody).
83
84 If you are not a developer, the delegated namespace(s)/attribute(s) are most
85 probably specified with the external component/entity you want to use.
86
87 The pseudo-namespace `http://jabber.org/protocol/disco#items:*` is used to
88 delegate remaining disco#items (i.e. items nodes not already handled by Prosody
89 itself).
90
91 Compatibility
92 =============
93
94 If you use it with Prosody 0.9 and a component, you need to patch
95 core/mod\_component.lua to fire a new signal. To do it, copy the following patch
96 in a, for example, /tmp/component.patch file:
97
98 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
99 --- a/plugins/mod_component.lua
100 +++ b/plugins/mod_component.lua
101 @@ -85,6 +85,7 @@
102 session.type = "component";
103 module:log("info", "External component successfully authenticated");
104 session.send(st.stanza("handshake"));
105 + module:fire_event("component-authenticated", { session = session });
106
107 return true;
108 end
109
110 Then, at the root of prosody, enter:
111
112 `patch -p1 < /tmp/component.patch`
113
114 ----- ----------------------------------------------------
115 0.11 Works
116 0.10 Works
117 0.9 Need a patched core/mod\_component.lua (see above)
118 ----- ----------------------------------------------------
119
120 Note
121 ====
122
123 This module is often used with mod\_privilege (c.f. XEP for more details)