Mercurial > prosody-modules

comparison mod_delegation/README.markdown @ 1803:4d73a1a6ba68

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