prosody-modules: mod_muc_limits/README.markdown annotate

annotate mod_muc_limits/README.markdown @ 5536:96dec7681af8

mod_firewall: Update user marks to store instantly via map store The original approach was to keep marks in memory only, and persist them at shutdown. That saves I/O, at the cost of potentially losing marks on an unclean shutdown. This change persists marks instantly, which may have some performance overhead but should be more "correct". It also splits the marking/unmarking into an event which may be watched or even fired by other modules.

author	Matthew Wild <mwild1@gmail.com>
date	Thu, 08 Jun 2023 16:20:42 +0100
parents	1534d0715d35
children	b97ae1cd7813

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).

Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5536:96dec7681af8