prosody-modules
c316ad1087d4
mod_firewall/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_firewall/README.markdown @ 4236:c316ad1087d4

mod_firewall: Some additional documentation improvements, particularly adding section links where needed
author Matthew Wild <mwild1@gmail.com>
date Fri, 06 Nov 2020 11:17:30 +0000
parent 4235:45606c9f529a
child 4583:bb8459c220c9
comparison
equal deleted inserted replaced
4235:45606c9f529a 4236:c316ad1087d4
71 Firewall rules should be written into text files, e.g. `ruleset.pfw` file. 71 Firewall rules should be written into text files, e.g. `ruleset.pfw` file.
72 One or more rule files can be specified in the configuration using: 72 One or more rule files can be specified in the configuration using:
73 73
74 firewall_scripts = { "path/to/ruleset.pfw", "path/to/ruleset2.pfw" } 74 firewall_scripts = { "path/to/ruleset.pfw", "path/to/ruleset2.pfw" }
75 75
76 If multiple files are specified and they both add rules to the same chains, 76 If multiple files are specified and they both add rules to the same [chains](#chains),
77 each file's rules will be processed in order, but the order of files is undefined. 77 each file's rules will be processed in order, but the order of files is undefined.
78 78
79 Reloading Prosody's configuration also reloads firewall rules. 79 Reloading Prosody's configuration also reloads firewall rules.
80 80
81 Make sure that `firewall_scripts` is in the global section of the configuration file 81 Make sure that `firewall_scripts` is in the global section of the configuration file
177 The "when-sni" default disables certificate verification when Prosody's HTTP client API doesn't support SNI, 177 The "when-sni" default disables certificate verification when Prosody's HTTP client API doesn't support SNI,
178 as in Prosody 0.11.6 and earlier. 178 as in Prosody 0.11.6 and earlier.
179 179
180 #### CHECK LIST 180 #### CHECK LIST
181 181
182 Checks whether a simple expression is found in a given list. 182 Checks whether a simple [expression](#expressions) is found in a given list.
183 183
184 Example: 184 Example:
185 185
186 %LIST blacklist: file:/etc/prosody/blacklist.txt 186 %LIST blacklist: file:/etc/prosody/blacklist.txt
187 187
257 `FROM` The JID in the 'from' attribute matches the given JID. 257 `FROM` The JID in the 'from' attribute matches the given JID.
258 `TO` The JID in the 'to' attribute matches the given JID. 258 `TO` The JID in the 'to' attribute matches the given JID.
259 `TO SELF` The stanza is sent by any of a user's resources to their own bare JID. 259 `TO SELF` The stanza is sent by any of a user's resources to their own bare JID.
260 `TO FULL JID` The stanza is addressed to a valid full JID on the local server (full JIDs include a resource at the end, and only exist for the lifetime of a single session, therefore the recipient must be online, or this check will not match). 260 `TO FULL JID` The stanza is addressed to a valid full JID on the local server (full JIDs include a resource at the end, and only exist for the lifetime of a single session, therefore the recipient must be online, or this check will not match).
261 261
262 The TO and FROM conditions both accept wildcards in the JID when the wildcard 262 The TO and FROM conditions both accept wildcards in the JID when it is
263 expression is enclosed in angle brackets ('\<...\>'). For example: 263 enclosed in angle brackets ('\<...\>'). For example:
264 264
265 # All users at example.com 265 # All users at example.com
266 FROM: <*>@example.com 266 FROM: <*>@example.com
267 267
268 # The user 'admin' on any subdomain of example.com 268 # The user 'admin' on any subdomain of example.com
278 # Match admin@example.com, and admin1@example.com, etc. 278 # Match admin@example.com, and admin1@example.com, etc.
279 FROM: <<admin%d*>>@example.com 279 FROM: <<admin%d*>>@example.com
280 280
281 **Note:** It is important to know that 'example.com' is a valid JID on 281 **Note:** It is important to know that 'example.com' is a valid JID on
282 its own, and does **not** match 'user@example.com'. To perform domain 282 its own, and does **not** match 'user@example.com'. To perform domain
283 whitelists or blacklists, use Zones. 283 whitelists or blacklists, use [Zones](#zones).
284 284
285 Condition Matches 285 Condition Matches
286 ---------------- --------------------------------------------------------------- 286 ---------------- ---------------------------------------------------------------
287 `FROM_EXACTLY` The JID in the 'from' attribute exactly matches the given JID 287 `FROM_EXACTLY` The JID in the 'from' attribute exactly matches the given JID
288 `TO_EXACTLY` The JID in the 'to' attribute exactly matches the given JID 288 `TO_EXACTLY` The JID in the 'to' attribute exactly matches the given JID
293 match all resources if no resource is specified to match. 293 match all resources if no resource is specified to match.
294 294
295 **Note:** Some chains execute before Prosody has performed any 295 **Note:** Some chains execute before Prosody has performed any
296 normalisation or validity checks on the to/from JIDs on an incoming 296 normalisation or validity checks on the to/from JIDs on an incoming
297 stanza. It is not advisable to perform access control or similar rules 297 stanza. It is not advisable to perform access control or similar rules
298 on JIDs in these chains (see the chain documentation for more info). 298 on JIDs in these chains (see the [chain documentation](#chains) for more info).
299 299
300 #### INSPECT 300 #### INSPECT
301 301
302 INSPECT takes a 'path' through the stanza to get a string (an attribute 302 INSPECT takes a 'path' through the stanza to get a string (an attribute
303 value or text content). An example is the best way to explain. Let's 303 value or text content). An example is the best way to explain. Let's
358 TYPE and PAYLOAD matched what we wanted before reaching the INSPECT rule). 358 TYPE and PAYLOAD matched what we wanted before reaching the INSPECT rule).
359 359
360 ### Roster 360 ### Roster
361 361
362 These functions access the roster of the recipient (only). Therefore they cannot (currently) 362 These functions access the roster of the recipient (only). Therefore they cannot (currently)
363 be used in some chains, such as for outgoing messages (the recipient may be on another server). 363 be used in some [chains](#chains), such as for outgoing messages (the recipient may be on another server).
364 364
365 Performance note: this check can potentially cause storage access (especially if the recipient 365 Performance note: this check can potentially cause storage access (especially if the recipient
366 is currently offline), so you may want to limit its use in high-traffic situations, and place 366 is currently offline), so you may want to limit its use in high-traffic situations, and place
367 it below other checks (such as a rate limiter). 367 it below other checks (such as a rate limiter).
368 368
381 #### SUBSCRIBED 381 #### SUBSCRIBED
382 382
383 Tests whether the recipient is subscribed to the sender, ie will receive 383 Tests whether the recipient is subscribed to the sender, ie will receive
384 presence updates from them. 384 presence updates from them.
385 385
386 Note that this *does* work, regardless of direction and which chain is 386 Note that this *does* work, regardless of direction and which [chain](#chain) is
387 used, since both the sender and the recipient will have mirrored roster 387 used, since both the sender and the recipient will have mirrored roster
388 entries. 388 entries.
389 389
390 ### Groups 390 ### Groups
391 391
516 516
517 You can use the 'on' keyword for this, like so: 517 You can use the 'on' keyword for this, like so:
518 518
519 LIMIT: normal on EXPRESSION 519 LIMIT: normal on EXPRESSION
520 520
521 For more information on expressions, see the section later in this document. 521 For more information on [expressions](#expressions), see the section later in this document.
522 522
523 Each value of 'EXPRESSION' has to be tracked individually in a table, which uses a small amount of memory. To prevent 523 Each value of 'EXPRESSION' has to be tracked individually in a table, which uses a small amount of memory. To prevent
524 memory exhaustion, the number of tracked values is limited to 1000 by default. You can override this by setting the 524 memory exhaustion, the number of tracked values is limited to 1000 by default. You can override this by setting the
525 maximum number of table entries when you define the rate: 525 maximum number of table entries when you define the rate:
526 526
618 618
619 Action Description 619 Action Description
620 --------------- ------------------------------------------------------------------------------------------------------------------------ 620 --------------- ------------------------------------------------------------------------------------------------------------------------
621 `LOG=message` Logs the given message to Prosody's log file. Optionally prefix it with a log level in square brackets, e.g. `[debug]` 621 `LOG=message` Logs the given message to Prosody's log file. Optionally prefix it with a log level in square brackets, e.g. `[debug]`
622 622
623 You can include expressions in log messages, using `$(...)` syntax. For example, to log the stanza that matched the rule, you can use `$(stanza)`, 623 You can include [expressions](#expressions) in log messages, using `$(...)` syntax. For example, to log the stanza that matched the rule,
624 or to log just the top tag of the stanza, use `$(stanza:top_tag())`. 624 you can use `$(stanza)`, or to log just the top tag of the stanza, use `$(stanza:top_tag())`. To fetch the sender JID, use `$(stanza.attr.from)`.
625 To fetch the sender JID, use `$(stanza.attr.from)`.
626 625
627 Example: 626 Example:
628 627
629 # Log all stanzas to user@example.com: 628 # Log all stanzas to user@example.com:
630 TO: user@example.com 629 TO: user@example.com