prosody-modules: mod_delegation/README.markdown annotate

annotate mod_delegation/README.markdown @ 5381:32a9817c7516

mod_firewall: Initialize compiled chunk just once for all handlers This should fix a case where some stateful dependencies (such as throttles) produce separate instances for every call to new_handler(), leading to surprising behaviour (e.g. rules executed via JUMP CHAIN vs ::deliver would have separate rate limits). This also adds better error handling in case the compiled code fails to run for some reason.

author	Matthew Wild <mwild1@gmail.com>
date	Fri, 28 Apr 2023 13:27:06 +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 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
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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	93
1993 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	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 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	97
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	98 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	99 --- a/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	100 +++ b/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	101 @@ -85,6 +85,7 @@
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	102 session.type = "component";
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	103 module:log("info", "External component successfully authenticated");
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	104 session.send(st.stanza("handshake"));
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	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 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	107 return true;
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	108 end
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	109
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	110 Then, at the root of prosody, enter:
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	111
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	112 `patch -p1 < /tmp/component.patch`
66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	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 66aaf7c3cb29 mod_delegation: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	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)

Mercurial > prosody-modules

annotate mod_delegation/README.markdown @ 5381:32a9817c7516