Mercurial > prosody-modules
annotate mod_privilege/README.markdown @ 5787:e79f9dec35c0
mod_c2s_conn_throttle: Reduce log level from error->info
Our general policy is that "error" should never be triggerable by remote
entities, and that it is always about something that requires admin
intervention. This satisfies neither condition.
The "warn" level can be used for unexpected events/behaviour triggered by
remote entities, and this could qualify. However I don't think failed auth
attempts are unexpected enough.
I selected "info" because it is what is also used for other notable session
lifecycle events.
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Thu, 07 Dec 2023 15:46:50 +0000 |
parents | 3ddab718f717 |
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: |
4913 | 3 - 'Stage-Beta' |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
4 summary: 'XEP-0356 (Privileged Entity) implementation' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
5 ... |
1782 | 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 | 9 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
10 Privileged Entity is an extension which allows entity/component to have |
4913 | 11 privileged access to server (set/get roster, send message on behalf of server, |
12 send IQ stanza on behalf of user, access presence information). It can be used | |
13 to build services independently of server (e.g.: PEP service). | |
1782 | 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 | 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 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
19 [XEP-0356](http://xmpp.org/extensions/xep-0356.html). |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
20 |
4913 | 21 Only the latest version of the XEP is implemented (using namespace |
22 `urn:xmpp:privilege:2`), if your component use an older version, please update. | |
23 | |
24 Note that roster permission is not fully implemented yet, roster pushes are not yet sent | |
25 to privileged entity. | |
26 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
27 Usage |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
28 ===== |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
29 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
30 To use the module, like usual add **"privilege"** to your |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
31 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
|
32 also need to activate the module in your component section: |
1782 | 33 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
34 modules_enabled = { |
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 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
37 "privilege"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
38 } |
1782 | 39 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
40 [...] |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
41 |
4913 | 42 Component "pubsub.yourdomain.tld" |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
43 component_secret = "yourpassword" |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
44 modules_enabled = {"privilege"} |
1782 | 45 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
46 then specify privileged entities **in your host section** like that: |
1782 | 47 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
48 VirtualHost "yourdomain.tld" |
1782 | 49 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
50 privileged_entities = { |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
51 ["romeo@montaigu.lit"] = { |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
52 roster = "get"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
53 presence = "managed_entity"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
54 }, |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
55 ["juliet@capulet.lit"] = { |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
56 roster = "both"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
57 message = "outgoing"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
58 presence = "roster"; |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
59 }, |
4913 | 60 ["pubsub.yourdomain.tld"] = { |
61 roster = "get"; | |
62 message = "outgoing"; | |
63 presence = "roster"; | |
64 iq = { | |
65 ["http://jabber.org/protocol/pubsub"] = "set"; | |
66 }; | |
67 }, | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
68 } |
1782 | 69 |
4913 | 70 Here *romeo@montaigu.lit* can **get** roster of anybody on the host, and will |
71 **have presence for any user** of the host, while *juliet@capulet.lit* can | |
72 **get** and **set** a roster, **send messages** on behalf of the server, and | |
73 **access presence of anybody linked to the host** (not only people on the | |
74 server, but also people in rosters of users of the server). | |
1782 | 75 |
4913 | 76 *pubsub.yourdomain.tld* is a Pubsub/PEP component which can **get** roster of |
77 anybody on the host, **send messages** on the behalf of the server, **access | |
78 presence of anybody linked to the host**, and **send IQ stanza of type "set" for | |
79 the namespace "http://jabber.org/protocol/pubsub"** (this can be used to | |
80 implement XEP-0376 "Pubsub Account Management"). | |
81 | |
82 **/!\\Â Be extra careful when you give a permission to an entity/component, it's | |
83 a powerful access, only do it if you absolutely trust the component/entity, and | |
84 you know where the software is coming from** | |
1782 | 85 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
86 Configuration |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
87 ============= |
1782 | 88 |
4913 | 89 roster |
90 ------ | |
91 | |
1782 | 92 All the permissions give access to all accounts of the virtual host. |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
93 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
94 -------- ------------------------------------------------ ---------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
95 roster none *(default)* No access to rosters |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
96 get Allow **read** access to rosters |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
97 set Allow **write** access to rosters |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
98 both Allow **read** and **write** access to rosters |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
99 -------- ------------------------------------------------ ---------------------- |
1782 | 100 |
4913 | 101 Note that roster implementation is incomplete at the moment, roster pushes are not yet |
102 send to privileged entity. | |
103 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
104 message |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
105 ------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
106 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
107 ------------------ ------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
108 none *(default)* Can't send message from server |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
109 outgoing Allow to send message on behalf of server (from bare jids) |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
110 ------------------ ------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
111 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
112 presence |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
113 -------- |
1782 | 114 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
115 ------------------ ------------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
116 none *(default)* Do not have extra presence information |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
117 managed\_entity Receive presence stanzas (except subscriptions) from host users |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
118 roster Receive all presence stanzas (except subsciptions) from host users and people in their rosters |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
119 ------------------ ------------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
120 |
4913 | 121 iq |
122 -- | |
123 | |
124 IQ permission is a table mapping allowed namespaces to allowed stanza type. When | |
125 a namespace is specified, IQ stanza of the specified type (see below) can be | |
126 sent if and only if the first child element of the IQ stanza has the specified | |
127 namespace. See https://xmpp.org/extensions/xep-0356.html#iq for details. | |
128 | |
129 Allowed stanza type: | |
130 | |
131 -------- ------------------------------------------- | |
132 get Allow IQ stanza of type **get** | |
133 set Allow IQ stanza of type **set** | |
134 both Allow IQ stanza of type **get** and **set** | |
135 -------- ------------------------------------------- | |
136 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
137 Compatibility |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
138 ============= |
1782 | 139 |
1992 | 140 If you use it with Prosody 0.9 and with a component, you need to patch |
141 core/mod\_component.lua to fire a new signal. To do it, copy the | |
142 following patch in a, for example, /tmp/component.patch file: | |
143 | |
144 ``` {.patch} | |
145 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua | |
146 --- a/plugins/mod_component.lua | |
147 +++ b/plugins/mod_component.lua | |
148 @@ -85,6 +85,7 @@ | |
149 session.type = "component"; | |
150 module:log("info", "External component successfully authenticated"); | |
151 session.send(st.stanza("handshake")); | |
152 + module:fire_event("component-authenticated", { session = session }); | |
153 | |
154 return true; | |
155 end | |
156 ``` | |
157 | |
158 Then, at the root of prosody, enter: | |
159 | |
160 `patch -p1 < /tmp/component.patch` | |
161 | |
4913 | 162 ----- -------------------------------------------------- |
163 trunk Works | |
164 0.12 Works | |
165 0.11 Works | |
1992 | 166 0.10 Works |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
167 0.9 Need a patched core/mod\_component.lua (see above) |
4913 | 168 ----- -------------------------------------------------- |
1782 | 169 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
170 Note |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
171 ==== |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
172 |
4913 | 173 This module is often used with mod\_delegation (c.f. XEP for more details) |