Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5648:c217f4edfc4f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc/mtail: Start of an mtail config Stashing it here in case anyone wants to continue working on it. Currently it's only counting log messages by level. Due to the permissions set by systemd on Prosody logs, mtail never managed to start correctly until permissions were manually relaxed.
author Kim Alvefur <zash@zash.se>
date Sun, 17 Sep 2023 13:36:30 +0200
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 ------- -------