Mercurial > prosody-modules

comparison mod_delegation/README.markdown @ 4709:679f1834dbdb

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