annotate mod_muc_limits.wiki @ 292:7699308b4f9b

Add
author Kim Alvefur <zash@zash.se>
date Fri, 13 Jul 2012 15:02:26 +0200
parents 440f4d3ee523
children 341195fb3d62
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
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
21 || *Name* || *Default value* || *Description* ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
22 || 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
23 || muc_burst_factor || 6 || Allow temporary bursts of this multiple. ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
24
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
25 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
26
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
27 = Algorithm =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
28
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
29 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
30
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
31 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
32
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
33 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
34
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
35 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
36
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
37 = Compatibility =
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
38 || Trunk || Works ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
39 || 0.8 || Doesn't work`*` ||
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
40
53e6f43b23fc Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
41 `*` 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).