prosody-modules
d611ed13df7e
mod_delegation/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_delegation/README.md @ 6209:d611ed13df7e draft

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 18 Mar 2025 00:16:25 +0700
parent 4709:mod_delegation/README.markdown@679f1834dbdb
comparison
equal deleted inserted replaced
6208:e20901443eae 6209:d611ed13df7e
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)