Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5064:7d33178c79f2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_sasl2: Add some brief dev notes about events to the README
author Matthew Wild <mwild1@gmail.com>
date Thu, 13 Oct 2022 22:48:57 +0100
parents 1534d0715d35
children b97ae1cd7813
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
3 - 'Stage-Beta'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 summary: 'Impose rate-limits on a MUC'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
5 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
10 This module allows you to control the maximum rate of 'events' in a MUC
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
11 room. This makes it useful to prevent room floods (whether malicious or
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 accidental).
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
14 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 This module limits the following events:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
19 - Room joins
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 - Nick changes
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
21 - Status changes
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 - Messages (including private messages)
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 The limit is for the room as a whole, not individual occupants in the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
25 room. Users with an affiliation (members, admins and owners) are not
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
26 limited.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
28 Configuration
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
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
31 Add the module to the MUC host (not the global modules\_enabled):
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
32
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33 Component "conference.example.com" "muc"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
34 modules_enabled = { "muc_limits" }
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 You can define (globally or per-MUC component) the following options:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37
2771
397dafbd79fc mod_muc_limits: Fix alignment of table columns
Kim Alvefur <zash@zash.se>
parents: 2770
diff changeset
38 Name Default value Description
397dafbd79fc mod_muc_limits: Fix alignment of table columns
Kim Alvefur <zash@zash.se>
parents: 2770
diff changeset
39 ------------------------ --------------- ----------------------------------------------
397dafbd79fc mod_muc_limits: Fix alignment of table columns
Kim Alvefur <zash@zash.se>
parents: 2770
diff changeset
40 muc\_event\_rate 0.5 The maximum number of events per second.
397dafbd79fc mod_muc_limits: Fix alignment of table columns
Kim Alvefur <zash@zash.se>
parents: 2770
diff changeset
41 muc\_burst\_factor 6 Allow temporary bursts of this multiple.
397dafbd79fc mod_muc_limits: Fix alignment of table columns
Kim Alvefur <zash@zash.se>
parents: 2770
diff changeset
42 muc\_max\_nick\_length 23 The maximum allowed length of user nicknames
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
43
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
44 For more understanding of how these values are used, see the algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
45 section below.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
47 Algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
48 =========
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
50 A certain number of events are allowed per second, given by
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
51 muc\_event\_rate. An event rate of 1 allows one event per second, and
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
52 event rate of 3 allows three events per second, and 0.5 allows one event
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
53 every two seconds, and so on.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
55 Obviously MUC conversations are not exactly steady streams of events.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
56 Sometimes multiple people will talk at once. This is handled by the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
57 muc\_burst\_factor option.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
59 A burst factor of 2 will allow 2 times as many events at once, for 2
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
60 seconds, before throttling will be triggered. A factor of 5, 5 times as
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
61 many events for 5 seconds.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
63 When the limit is reached, an error response will be generated telling
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
64 the user the MUC is overactive, and asking them to try again.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
66 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
67 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
3417
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
69 ------- ------------------
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
70 trunk Works
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
71 0.11 Works
2770
7cd877aa6095 mod_muc_limits: Update compatibility table
Matthew Wild <mwild1@gmail.com>
parents: 2769
diff changeset
72 0.10 Works
7cd877aa6095 mod_muc_limits: Update compatibility table
Matthew Wild <mwild1@gmail.com>
parents: 2769
diff changeset
73 0.9 Works
1833
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
74 0.8 Doesn't work[^1]
3417
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
75 ------- ------------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76
1833
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
77 [^1]: This module can be made to work in 0.8 (and *maybe* previous
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
78 versions) of Prosody by copying the new
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
79 [util.throttle](http://hg.prosody.im/trunk/raw-file/fc8a22936b3c/util/throttle.lua)
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
80 into your Prosody source directory (into the util/ subdirectory).