Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5747:111e970213a0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_restrict_xmpp: Fix remaining hard-coded role name
author Matthew Wild <mwild1@gmail.com>
date Thu, 30 Nov 2023 18:05:42 +0000
parents ee335399d90e
children
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
5602
bae2f4830a93 mod_muc_limits: Set syntax of config snippets to enable syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 5601
diff changeset
33 ```lua
bae2f4830a93 mod_muc_limits: Set syntax of config snippets to enable syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 5601
diff changeset
34 Component "conference.example.com" "muc"
bae2f4830a93 mod_muc_limits: Set syntax of config snippets to enable syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 5601
diff changeset
35 modules_enabled = { "muc_limits" }
bae2f4830a93 mod_muc_limits: Set syntax of config snippets to enable syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 5601
diff changeset
36 ```
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 You can define (globally or per-MUC component) the following options:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39
5601
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
40 Name Default value Description
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
41 --------------------------- --------------- ----------------------------------------------------------
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
42 muc_event_rate 0.5 The maximum number of events per second.
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
43 muc_burst_factor 6 Allow temporary bursts of this multiple.
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
44 muc_max_nick_length 23 The maximum allowed length of user nicknames
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
45 muc_max_char_count 5664 The maximum allowed number of bytes in a message
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
46 muc_max_line_count 23 The maximum allowed number of lines in a message
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
47 muc_limit_base_cost 1 Base cost of sending a stanza
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
48 muc_line_count_multiplier 0.1 Additional cost of each newline in the body of a message
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
49
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
50 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
51 section below.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
53 Algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
54 =========
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
56 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
57 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
58 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
59 every two seconds, and so on.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
61 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
62 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
63 muc\_burst\_factor option.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
65 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
66 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
67 many events for 5 seconds.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
69 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
70 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
71
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
72 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
73 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
5603
ee335399d90e mod_muc_limits: Drop unsupported Prosody versions from Compatibility table
Kim Alvefur <zash@zash.se>
parents: 5602
diff changeset
75 ------- -------
3417
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
76 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
77 0.11 Works
5603
ee335399d90e mod_muc_limits: Drop unsupported Prosody versions from Compatibility table
Kim Alvefur <zash@zash.se>
parents: 5602
diff changeset
78 ------- -------