Mercurial > prosody-modules
annotate mod_delegation/README.markdown @ 5765:78368d2865dd
mod_s2s_smacks_timeout: Add note about being merged in trunk mod_s2s
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 03 Dec 2023 21:25:39 +0100 |
parents | 679f1834dbdb |
children |
rev | line source |
---|---|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
1 --- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
2 labels: |
2759
4bf60727459b
mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents:
1993
diff
changeset
|
3 - 'Stage-Beta' |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
4 summary: 'XEP-0355 (Namespace Delegation) implementation' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
5 ... |
1782 | 6 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
7 Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
8 ============ |
1782 | 9 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
10 Namespace Delegation is an extension which allows server to delegate some |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
11 features handling to an entity/component. Typical use case is an external PEP |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
12 service, but it can be used more generally when your preferred server lack one |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
13 internal feature, and you found an external component which can do it. |
1782 | 14 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
15 Details |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
16 ======= |
1782 | 17 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
18 You can have all the details by reading the |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
19 [XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin mode is |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
20 implemented so far. |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
21 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
22 Usage |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
23 ===== |
1782 | 24 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
25 To use the module, like usual add **"delegation"** to your *modules\_enabled*. |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
26 Note that if you use it with a local component, you also need to activate the |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
27 module in your component section: |
1782 | 28 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
29 modules_enabled = { |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
30 [...] |
2759
4bf60727459b
mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents:
1993
diff
changeset
|
31 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
32 "delegation"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
33 } |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
34 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
35 [...] |
1782 | 36 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
37 Component "youcomponent.yourdomain.tld" |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
38 component_secret = "yourpassword" |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
39 modules_enabled = {"delegation"} |
1782 | 40 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
41 then specify delegated namespaces **in your host section** like that: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
42 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
43 VirtualHost "yourdomain.tld" |
1782 | 44 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
45 delegations = { |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
46 ["urn:xmpp:mam:2"] = { |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
47 filtering = {"node"}; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
48 jid = "pubsub.yourdomain.tld"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
49 }, |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
50 ["http://jabber.org/protocol/pubsub"] = { |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
51 jid = "pubsub.yourdomain.tld"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
52 }, |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
53 ["http://jabber.org/protocol/pubsub#owner"] = { |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
54 jid = "pubsub.yourdomain.tld"; |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
55 }, |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
56 ["urn:xmpp:delegation:2:bare:disco#info:*"] = { |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
57 jid = "pubsub.yourdomain.tld"; |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
58 }, |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
59 ["urn:xmpp:delegation:2:bare:disco#items:*"] = { |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
60 jid = "pubsub.yourdomain.tld"; |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
61 }, |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
62 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
63 } |
1782 | 64 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
65 Here all MAM requests with a "node" attribute (i.e. all MAM pubsub request) will |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
66 be delegated to pubsub.yourdomain.tld. Similarly, all pubsub request to the host |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
67 (i.e. the PEP requests) will be delegated to pubsub.yourdomain.tld. Check the |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
68 XEP for the meaning of "urn:xmpp:delegation:2:bare:disco#info:*" and |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
69 "urn:xmpp:delegation:2:bare:disco#items:*". |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
70 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
71 **/!\ Be extra careful when you give a delegation to an entity/component, it's a |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
72 powerful access, only do it if you absolutely trust the component/entity, and |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
73 you know where the software is coming from** |
1782 | 74 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
75 Configuration |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
76 ============= |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
77 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
78 The configuration is done with a table which map delegated namespace to |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
79 namespace data. Namespace data MUST have a **jid** (in the form **jid = |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
80 "delegated@domain.tld"**) and MAY have an additional **filtering** array. If |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
81 filtering is present, request with attributes in the array will be delegated, |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
82 others will be treated normally (i.e. by Prosody). |
1782 | 83 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
84 If you are not a developer, the delegated namespace(s)/attribute(s) are most |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
85 probably specified with the external component/entity you want to use. |
1782 | 86 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
87 The pseudo-namespace `http://jabber.org/protocol/disco#items:*` is used to |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
88 delegate remaining disco#items (i.e. items nodes not already handled by Prosody |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
89 itself). |
2759
4bf60727459b
mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents:
1993
diff
changeset
|
90 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
91 Compatibility |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
92 ============= |
1782 | 93 |
1993 | 94 If you use it with Prosody 0.9 and a component, you need to patch |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
95 core/mod\_component.lua to fire a new signal. To do it, copy the following patch |
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
96 in a, for example, /tmp/component.patch file: |
1993 | 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 }); | |
2759
4bf60727459b
mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents:
1993
diff
changeset
|
106 |
1993 | 107 return true; |
108 end | |
109 | |
110 Then, at the root of prosody, enter: | |
111 | |
112 `patch -p1 < /tmp/component.patch` | |
113 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
114 ----- ---------------------------------------------------- |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
115 0.11 Works |
1993 | 116 0.10 Works |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
117 0.9 Need a patched core/mod\_component.lua (see above) |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
118 ----- ---------------------------------------------------- |
1782 | 119 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
120 Note |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
121 ==== |
1782 | 122 |
4709
679f1834dbdb
mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents:
2876
diff
changeset
|
123 This module is often used with mod\_privilege (c.f. XEP for more details) |