annotate mod_muc_limits.wiki @ 338:d3f2060ac16a

Re-add Installation section.
author florob@babelmonkeys.de
date Sat, 06 Apr 2013 16:11:15 +0000
parents 341195fb3d62
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
257
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
1 #summary Impose rate-limits on a MUC
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
2 #labels Stage-Beta
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
3
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
4 = Introduction =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
5
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
6 This module allows you to control the maximum rate of 'events' in a MUC room. This makes it useful to prevent room floods (whether malicious or accidental).
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
7
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
8 = Details =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
9
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
10 This module limits the following events:
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
11
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
12 * Room joins
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
13 * Nick changes
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
14 * Status changes
258
440f4d3ee523 Private messages are also limited
MWild1@gmail.com
parents: 257
diff changeset
15 * Messages (including private messages)
257
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
16
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
17 The limit is for the room as a whole, not individual occupants in the room. Users with an affiliation (members, admins and owners) are not limited.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
18
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
19 = Configuration =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
20
293
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
21 Add the module to the MUC host (not the global modules_enabled):
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
22
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
23 {{{
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
24 Component "conference.example.com" "muc"
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
25 modules_enabled = { "muc_limits" }
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
26 }}}
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
27
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
28 You can define (globally or per-MUC component) the following options:
341195fb3d62 Added config example
MWild1@gmail.com
parents: 258
diff changeset
29
257
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
30 || *Name* || *Default value* || *Description* ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
31 || muc_event_rate || 0.5 || The maximum number of events per second. ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
32 || muc_burst_factor || 6 || Allow temporary bursts of this multiple. ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
33
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
34 For more understanding of how these values are used, see the algorithm section below.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
35
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
36 = Algorithm =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
37
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
38 A certain number of events are allowed per second, given by muc_event_rate. An event rate of 1 allows one event per second, and event rate of 3 allows three events per second, and 0.5 allows one event every two seconds, and so on.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
39
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
40 Obviously MUC conversations are not exactly steady streams of events. Sometimes multiple people will talk at once. This is handled by the muc_burst_factor option.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
41
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
42 A burst factor of 2 will allow 2 times as many events at once, for 2 seconds, before throttling will be triggered. A factor of 5, 5 times as many events for 5 seconds.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
43
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
44 When the limit is reached, an error response will be generated telling the user the MUC is overactive, and asking them to try again.
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
45
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
46 = Compatibility =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
47 || Trunk || Works ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
48 || 0.8 || Doesn't work`*` ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
49
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
50 `*` This module can be made to work in 0.8 (and _maybe_ previous versions) of Prosody by copying the new [http://hg.prosody.im/trunk/raw-file/fc8a22936b3c/util/throttle.lua util.throttle] into your Prosody source directory (into the util/ subdirectory).