--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_delegation/README.markdown Fri Aug 28 18:03:58 2015 +0200
@@ -0,0 +1,110 @@
+---
+labels:
+- 'Stage-Alpha'
+summary: 'XEP-0355 (Namespace Delegation) implementation'
+...
+
+Introduction
+============
+
+Namespace Delegation is an extension which allows server to delegate
+some features handling to an entity/component. Typical use case is an
+external PEP service, but it can be used more generally when your
+prefered server lack one internal feature and you found an external
+component which can do it.
+
+Details
+=======
+
+You can have all the details by reading the
+[XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin
+mode is implemented so far.
+
+If you use it with a component, you need to patch
+core/mod\_component.lua to fire a new signal. To do it, copy the
+following patch in a, for example, /tmp/component.patch file:
+
+ diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
+ --- a/plugins/mod_component.lua
+ +++ b/plugins/mod_component.lua
+ @@ -85,6 +85,7 @@
+ session.type = "component";
+ module:log("info", "External component successfully authenticated");
+ session.send(st.stanza("handshake"));
+ + module:fire_event("component-authenticated", { session = session });
+
+ return true;
+ end
+
+Then, at the root of prosody, enter:
+
+`patch -p1 < /tmp/component.patch`
+
+Usage
+=====
+
+To use the module, like usual add **"delegation"** to your
+modules\_enabled. Note that if you use it with a local component, you
+also need to activate the module in your component section:
+
+ modules_enabled = {
+ [...]
+
+ "delegation";
+ }
+
+ [...]
+
+ Component "youcomponent.yourdomain.tld"
+ component_secret = "yourpassword"
+ modules_enabled = {"delegation"}
+
+then specify delegated namespaces **in your host section** like that:
+
+ VirtualHost "yourdomain.tld"
+
+ delegations = {
+ ["urn:xmpp:mam:0"] = {
+ filtering = {"node"};
+ jid = "pubsub.yourdomain.tld";
+ },
+ ["http://jabber.org/protocol/pubsub"] = {
+ jid = "pubsub.yourdomain.tld";
+ },
+ }
+
+Here all MAM requests with a "node" attribute (i.e. all MAM pubsub
+request) will be delegated to pubsub.yourdomain.tld. Similarly, all
+pubsub request to the host (i.e. the PEP requests) will be delegated to
+pubsub.yourdomain.tld.
+
+**/! Be extra careful when you give a delegation to an entity/component,
+it's a powerful access, only do it if you absoly trust the
+component/entity, and you know where the software is coming from**
+
+Configuration
+=============
+
+The configuration is done with a table which map delegated namespace to
+namespace data. Namespace data MUST have a **jid** (in the form **jid =
+"delegated@domain.tld"**) and MAY have an additional **filtering**
+array. If filtering is present, request with attributes in the array
+will be delegated, other will be treated normally (i.e. by Prosody).
+
+If your are not a developper, the delegated namespace(s)/attribute(s)
+are most probably specified with the external component/entity you want
+to use.
+
+Compatibility
+=============
+
+ ----- ----------------------------------------------------
+ dev Need a patched core/mod\_component.lua (see above)
+ 0.9 Need a patched core/mod\_component.lua (see above)
+ ----- ----------------------------------------------------
+
+Note
+====
+
+This module is often used with mod\_privilege (c.f. XEP for more
+details)