prosody-modules: mod_muc_limits/README.markdown annotate

annotate mod_muc_limits/README.markdown @ 5585:5b316088bef5

mod_rest: Use logger of HTTP request in trunk In Prosody trunk rev c975dafa4303 each HTTP request gained its own log sink, to make it easy to log things related to each request and group those messages. Especially where async is used, spreading the request and response apart as mod_rest does with iq stanzas, this grouped logging should help find related messages.

author	Kim Alvefur <zash@zash.se>
date	Fri, 07 Jul 2023 00:10:37 +0200
parents	d52cc18f0aa8
children	6680a1f53353

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
5565 b97ae1cd7813 mod_muc_limits: Normalise README markdown syntax (thanks pandoc) Kim Alvefur <zash@zash.se> parents: 3417 diff changeset	38 Name Default value Description
5566 f71d66bd87be mod_muc_limits: Add a limit on number of lines per message Kim Alvefur <zash@zash.se> parents: 5565 diff changeset	39 --------------------- --------------- --------------------------------------------------
5565 b97ae1cd7813 mod_muc_limits: Normalise README markdown syntax (thanks pandoc) Kim Alvefur <zash@zash.se> parents: 3417 diff changeset	40 muc_event_rate 0.5 The maximum number of events per second.
b97ae1cd7813 mod_muc_limits: Normalise README markdown syntax (thanks pandoc) Kim Alvefur <zash@zash.se> parents: 3417 diff changeset	41 muc_burst_factor 6 Allow temporary bursts of this multiple.
b97ae1cd7813 mod_muc_limits: Normalise README markdown syntax (thanks pandoc) Kim Alvefur <zash@zash.se> parents: 3417 diff changeset	42 muc_max_nick_length 23 The maximum allowed length of user nicknames
5567 d52cc18f0aa8 mod_muc_limits: Add a limit on number of bytes in a message body Kim Alvefur <zash@zash.se> parents: 5566 diff changeset	43 muc_max_char_count 5664 The maximum allowed number of bytes in a message
5566 f71d66bd87be mod_muc_limits: Add a limit on number of lines per message Kim Alvefur <zash@zash.se> parents: 5565 diff changeset	44 muc_max_line_count 23 The maximum allowed number of lines in a message
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	45
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	46 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	47 section below.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	48
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	49 Algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	50 =========
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	51
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	52 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	53 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	54 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	55 every two seconds, and so on.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	56
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	57 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	58 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	59 muc\_burst\_factor option.
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 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	62 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	63 many events for 5 seconds.
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 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	66 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	67
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	68 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	69 =============
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	70
3417 1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11 Kim Alvefur <zash@zash.se> parents: 3402 diff changeset	71 ------- ------------------
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11 Kim Alvefur <zash@zash.se> parents: 3402 diff changeset	72 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	73 0.11 Works
2770 7cd877aa6095 mod_muc_limits: Update compatibility table Matthew Wild <mwild1@gmail.com> parents: 2769 diff changeset	74 0.10 Works
7cd877aa6095 mod_muc_limits: Update compatibility table Matthew Wild <mwild1@gmail.com> parents: 2769 diff changeset	75 0.9 Works
1833 52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	76 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	77 ------- ------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	78
1833 52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	79 [^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	80 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	81 [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	82 into your Prosody source directory (into the util/ subdirectory).

Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5585:5b316088bef5