Mercurial > prosody-modules

comparison mod_firewall/README.markdown @ 2369:2fb11d34087e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_firewall: README: Update for LIMIT 'on' and document expression syntax
author Matthew Wild <mwild1@gmail.com>
date Tue, 15 Nov 2016 21:02:46 +0000
parents 97e63e8f0f32
children 5fe483b73fd2
comparison
equal deleted inserted replaced
2368:7e1d8c46d788 2369:2fb11d34087e
287 ----------- -------------------------------------------------------------------------------------------------- 287 ----------- --------------------------------------------------------------------------------------------------
288 `LIMIT` When the named limit is 'used up'. Using this condition automatically counts against that limit. 288 `LIMIT` When the named limit is 'used up'. Using this condition automatically counts against that limit.
289 289
290 **Note:** Reloading mod\_firewall resets the current state of any 290 **Note:** Reloading mod\_firewall resets the current state of any
291 limiters. 291 limiters.
292
293 #### Dynamic limits
294
295 Sometimes you may want to have multiple throttles in a single condition, using some property of the session or stanza
296 to determine which throttle to use. For example, you might have a limit for incoming stanzas, but you want to limit by
297 sending JID, instead of all incoming stanzas sharing the same limit.
298
299 You can use the 'on' keyword for this, like so:
300
301 LIMIT: normal on EXPRESSION
302
303 For more information on expressions, see the section later in this document.
292 304
293 ### Session marking 305 ### Session marking
294 306
295 It is possible to 'mark' sessions (see the MARK_ORIGIN action below). To match stanzas from marked sessions, use the 307 It is possible to 'mark' sessions (see the MARK_ORIGIN action below). To match stanzas from marked sessions, use the
296 `ORIGIN_MARKED` condition. 308 `ORIGIN_MARKED` condition.
383 395
384 # Log all stanzas to user@example.com: 396 # Log all stanzas to user@example.com:
385 TO: user@example.com 397 TO: user@example.com
386 LOG=[debug] User received: $(stanza) 398 LOG=[debug] User received: $(stanza)
387 399
400 More info about expressions can be found below.
401
388 Chains 402 Chains
389 ------ 403 ------
390 404
391 Rules are grouped into "chains", which are injected at particular points in Prosody's routing code. 405 Rules are grouped into "chains", which are injected at particular points in Prosody's routing code.
392 406
429 DROP. 443 DROP.
430 444
431 Action Description 445 Action Description
432 ------------------------ ------------------------------------------------------------------------ 446 ------------------------ ------------------------------------------------------------------------
433 `JUMP_CHAIN=name` Switches chains, and passes the stanza through the rules in chain 'name'. If the new chain causes the stanza to be dropped/redirected, the current chain halts further processing. 447 `JUMP_CHAIN=name` Switches chains, and passes the stanza through the rules in chain 'name'. If the new chain causes the stanza to be dropped/redirected, the current chain halts further processing.
448
449 Expressions
450 -----------
451
452 Some conditions and actions in rules support "expressions" in their parameters (their documentation will indicate if this is the case). Most parameters
453 are static once the firewall script is loaded and compiled internally, however parameters that allow expressions can be dynamically calculated when a
454 rule is being run.
455
456 There are two kinds of expression that you can use: stanza expressions, and code expressions.
457
458 Stanza expressions are of the form `$<...>`, where `...` is a stanza path. For syntax of stanza paths, see the documentation for the 'INSPECT' condition
459 above.
460
461 Example:
462
463 LOG=Matched a stanza from $<@from> to $<@to>
464
465 If the path does not match (e.g. the element isn't found, or the attribute doesn't exist) it will return the text `<undefined>`. You can override this
466 by specifying an alternative default value, using the syntax `$<path||default>`.
467
468 Code expressions use `$(...)` syntax. Code expressions are powerful, and allow unconstrained access to Prosody's internal environment. Therefore
469 code expressions are typically for advanced use-cases only. You may want to refer to Prosody's [developer documentation](https://prosody.im/doc/developers)
470 for more information. In particular, within code expressions you may access the 'session' object, which is the session object of the origin of the stanza,
471 and the 'stanza' object, which is the stanza being considered within the current rule. Whatever value the expression returns will be converted to a string.
472
473 Example to limit stanzas per session type:
474
475 LIMIT: normal on $(session.type)