Mercurial > prosody-modules

comparison mod_privilege/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_privilege/README.wiki@29f3d6b7ad16
children 8dda3d7d616f
comparison
equal deleted inserted replaced
1802:0ab737feada6 1803:4d73a1a6ba68
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'XEP-0356 (Privileged Entity) implementation'
5 ...
6
7 Introduction
8 ============
9
10 Privileged Entity is an extension which allows entity/component to have
11 privileged access to server (set/get roster, send message on behalf of
12 server, access presence informations). It can be used to build services
13 independently of server (e.g.: PEP service).
14
15 Details
16 =======
17
18 You can have all the details by reading the
19 [XEP-0356](http://xmpp.org/extensions/xep-0356.html).
20
21 If you use it with a component, you need to patch
22 core/mod\_component.lua to fire a new signal. To do it, copy the
23 following patch in a, for example, /tmp/component.patch file:
24
25 ``` {.patch}
26 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
27 --- a/plugins/mod_component.lua
28 +++ b/plugins/mod_component.lua
29 @@ -85,6 +85,7 @@
30 session.type = "component";
31 module:log("info", "External component successfully authenticated");
32 session.send(st.stanza("handshake"));
33 + module:fire_event("component-authenticated", { session = session });
34
35 return true;
36 end
37 ```
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 **"privilege"** 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 "privilege";
54 }
55
56 [...]
57
58 Component "youcomponent.yourdomain.tld"
59 component_secret = "yourpassword"
60 modules_enabled = {"privilege"}
61
62 then specify privileged entities **in your host section** like that:
63
64 VirtualHost "yourdomain.tld"
65
66 privileged_entities = {
67 ["romeo@montaigu.lit"] = {
68 roster = "get";
69 presence = "managed_entity";
70 },
71 ["juliet@capulet.lit"] = {
72 roster = "both";
73 message = "outgoing";
74 presence = "roster";
75 },
76 }
77
78 Here *romeo@montaigu.lit* can **get** roster of anybody on the host, and
79 will **have presence for any user** of the host, while
80 *juliet@capulet.lit* can **get** and **set** a roster, **send messages**
81 on the behalf of the server, and **access presence of anybody linked to
82 the host** (not only people on the server, but also people in rosters of
83 users of the server).
84
85 **/! Be extra careful when you give a permission to an entity/component,
86 it's a powerful access, only do it if you absoly trust the
87 component/entity, and you know where the software is coming from**
88
89 Configuration
90 =============
91
92 All the permissions give access to all accounts of the virtual host.
93
94 -------- ------------------------------------------------ ----------------------
95 roster none *(default)* No access to rosters
96 get Allow **read** access to rosters
97 set Allow **write** access to rosters
98 both Allow **read** and **write** access to rosters
99 -------- ------------------------------------------------ ----------------------
100
101 message
102 -------
103
104 ------------------ ------------------------------------------------------------
105 none *(default)* Can't send message from server
106 outgoing Allow to send message on behalf of server (from bare jids)
107 ------------------ ------------------------------------------------------------
108
109 presence
110 --------
111
112 ------------------ ------------------------------------------------------------------------------------------------
113 none *(default)* Do not have extra presence information
114 managed\_entity Receive presence stanzas (except subscriptions) from host users
115 roster Receive all presence stanzas (except subsciptions) from host users and people in their rosters
116 ------------------ ------------------------------------------------------------------------------------------------
117
118 Compatibility
119 =============
120
121 ----- ----------------------------------------------------
122 dev Need a patched core/mod\_component.lua (see above)
123 0.9 Need a patched core/mod\_component.lua (see above)
124 ----- ----------------------------------------------------
125
126 Note
127 ====
128
129 This module is often used with mod\_delegation (c.f. XEP for more
130 details)