prosody-modules: mod_delegation/README.markdown annotate

annotate mod_delegation/README.markdown @ 4421:94805a7e7b30

mod_invites: rework CLI parsing to support groups To make this sensible, the code had to move from rather simple parsing to something which looks more like getopt or your typical shell script.

author	Jonas Schäfer <jonas@wielicki.name>
date	Sun, 31 Jan 2021 19:16:36 +0100
parents	ea6b5321db50
children	679f1834dbdb

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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	9
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	10 Namespace Delegation is an extension which allows server to delegate
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	11 some features handling to an entity/component. Typical use case is an
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	12 external PEP service, but it can be used more generally when your
2876 ea6b5321db50 README files: Fix typos Kim Alvefur <zash@zash.se> parents: 2759 diff changeset	13 preferred server lack one internal feature and you found an external
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	14 component which can do it.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	15
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	16 Details
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	17 =======
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	18
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	19 You can have all the details by reading the
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	20 [XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	21 mode is implemented so far.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	22
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	23 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	24 =====
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	25
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	26 To use the module, like usual add "delegation" to your
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	27 modules\_enabled. Note that if you use it with a local component, you
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	28 also need to activate the module in your component section:
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	29
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	30 modules_enabled = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	31 [...]
2759 4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	32
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	33 "delegation";
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
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	36 [...]
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	37
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	38 Component "youcomponent.yourdomain.tld"
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	39 component_secret = "yourpassword"
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	40 modules_enabled = {"delegation"}
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	41
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	42 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	43
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	44 VirtualHost "yourdomain.tld"
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	45
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	46 delegations = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	47 ["urn:xmpp:mam:0"] = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	48 filtering = {"node"};
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	49 jid = "pubsub.yourdomain.tld";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	50 },
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	51 ["http://jabber.org/protocol/pubsub"] = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	52 jid = "pubsub.yourdomain.tld";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	53 },
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	54 }
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	55
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	56 Here all MAM requests with a "node" attribute (i.e. all MAM pubsub
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	57 request) will be delegated to pubsub.yourdomain.tld. Similarly, all
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	58 pubsub request to the host (i.e. the PEP requests) will be delegated to
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	59 pubsub.yourdomain.tld.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	60
2759 4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	61 **/!\ Be extra careful when you give a delegation to an entity/component,
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	62 it's a powerful access, only do it if you absoly trust the
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	63 component/entity, and you know where the software is coming from**
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	64
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	65 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	66 =============
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	67
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	68 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	69 namespace data. Namespace data MUST have a jid (in the form **jid =
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	70 "delegated@domain.tld") and MAY have an additional filtering**
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	71 array. If filtering is present, request with attributes in the array
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	72 will be delegated, other will be treated normally (i.e. by Prosody).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	73
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	74 If your are not a developper, the delegated namespace(s)/attribute(s)
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	75 are most probably specified with the external component/entity you want
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	76 to use.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	77
2759 4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	78 The pseudo-namespace `http://jabber.org/protocol/disco#items:*` is used
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	79 to delegate remaining disco#items (i.e. items nodes not already handled
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	80 by Prosody itself).
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta Goffi <goffi@goffi.org> parents: 1993 diff changeset	81
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	82 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	83 =============
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	84
1993 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	85 If you use it with Prosody 0.9 and a component, you need to patch
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	86 core/mod\_component.lua to fire a new signal. To do it, copy the
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	87 following patch in a, for example, /tmp/component.patch file:
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	88
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	89 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	90 --- a/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	91 +++ b/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	92 @@ -85,6 +85,7 @@
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	93 session.type = "component";
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	94 module:log("info", "External component successfully authenticated");
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	95 session.send(st.stanza("handshake"));
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	96 + 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	97
1993 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	98 return true;
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	99 end
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	100
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	101 Then, at the root of prosody, enter:
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	102
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	103 `patch -p1 < /tmp/component.patch`
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	104
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	105 ----- ----------------------------------------------------
1993 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	106 0.10 Works
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	107 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	108 ----- ----------------------------------------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	109
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	110 Note
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	111 ====
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	112
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	113 This module is often used with mod\_privilege (c.f. XEP for more
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	114 details)

Mercurial > prosody-modules

annotate mod_delegation/README.markdown @ 4421:94805a7e7b30