prosody-modules: mod_firewall/README.markdown annotate

annotate mod_firewall/README.markdown @ 2095:3b4a6d255d7a

mod_firewall: README: Add note about BOUNCE and error stanzas/iq results

author	Matthew Wild <mwild1@gmail.com>
date	Wed, 16 Mar 2016 12:42:51 +0000
parents	7b9520479e99
children	b75d29a162cd

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-Alpha'
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	4 summary: 'A rule-based stanza filtering module'
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	5 ...
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	6
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	7 ------------------------------------------------------------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	8
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	9 Note: mod\_firewall is in its very early stages. This documentation
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	10 is liable to change, and some described functionality may be missing,
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	11 incomplete or contain bugs. Feedback is welcome in the comments section
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	12 at the bottom of this page.
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 ------------------------------------------------------------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	15
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	16 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	17 ============
1782 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 A firewall is an invaluable tool in the sysadmin's toolbox. However
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	20 while low-level firewalls such as iptables and pf are incredibly good at
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	21 what they do, they are generally not able to handle application-layer
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	22 rules.
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 goal of mod\_firewall is to provide similar services at the XMPP
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	25 layer. Based on rule scripts it can efficiently block, bounce, drop,
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	26 forward, copy, redirect stanzas and more! Furthermore all rules can be
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	27 applied and updated dynamically at runtime without restarting the
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	28 server.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	29
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	30 Details
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	31 =======
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	32
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	33 mod\_firewall loads one or more scripts, and compiles these to Lua code
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	34 that reacts to stanzas flowing through Prosody. The firewall script
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	35 syntax is unusual, but straightforward.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	36
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	37 A firewall script is dominated by rules. Each rule has two parts:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	38 conditions, and actions. When a stanza matches all of the conditions,
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	39 all of the actions are executed in order.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	40
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	41 Here is a simple example to block stanzas from spammer@example.com:
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	42
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	43 FROM: spammer@example.com
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	44 DROP.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	45
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	46 FROM is a condition, and DROP is an action. This is about as simple as
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	47 it gets. How about heading to the other extreme? Let's demonstrate
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	48 something more complex that mod\_firewall can do for you:
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 %ZONE myorganisation: staff.myorg.example, support.myorg.example
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 ENTERING: myorganisation
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	53 KIND: message
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	54 TIME: 12am-9am, 5pm-12am, Saturday, Sunday
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	55 REPLY=Sorry, I am afraid our office is closed at the moment. If you need assistance, please call our 24-hour support line on 123-456-789.
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 This rule will reply with a short message whenever someone tries to send
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	58 a message to someone at any of the hosts defined in the 'myorganisation'
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	59 outside of office hours.
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 Firewall rules should be written to a `ruleset.pfw` file. Multiple such
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	62 rule files can be specified in the configuration using:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	63
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	64 firewall_scripts = { "path/to/ruleset.pfw" }
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 Conditions
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	67 ----------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	68
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	69 All conditions must come before any action in a rule block. The
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	70 condition name is followed by a colon (':'), and the value to test for.
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 A condition can be preceded or followed by `NOT` to negate its match.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	73 For example:
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	74
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	75 NOT FROM: user@example.com
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	76 KIND NOT: message
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	77
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	78 ### Zones
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	79
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	80 A 'zone' is one or more hosts or JIDs. It is possible to match when a
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	81 stanza is entering or leaving a zone, while at the same time not
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	82 matching traffic passing between JIDs in the same zone.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	83
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	84 Zones are defined at the top of a script with the following syntax (they
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	85 are not part of a rule block):
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	86
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	87 %ZONE myzone: host1, host2, user@host3, foo.bar.example
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	88
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	89 A host listed in a zone also matches all users on that host (but not
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	90 subdomains).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	91
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	92 The following zone-matching conditions are supported:
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	93
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	94 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	95 ------------ ------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	96 `ENTERING` When a stanza is entering the named zone
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	97 `LEAVING` When a stanza is leaving the named zone
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	98
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	99 ### Stanza matching
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	100
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	101 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	102 ----------- ------------------------------------------------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	103 `KIND` The kind of stanza. May be 'message', 'presence' or 'iq'
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	104 `TYPE` The type of stanza. This varies depending on the kind of stanza. See 'Stanza types' below for more information.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	105 `PAYLOAD` The stanza contains a child with the given namespace. Useful for determining the type of an iq request, or whether a message contains a certain extension.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	106 `INSPECT` The node at the specified path exists or matches a given string. This allows you to look anywhere inside a stanza. See below for examples and more.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	107
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	108 #### Stanza types
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	109
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	110 Stanza Valid types
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	111 ---------- ------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	112 iq get, set, result, error
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	113 presence available, unavailable, probe, subscribe, subscribed, unsubscribe, unsubscribed, error
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	114 message normal, chat, groupchat, headline, error
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	115
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	116 Note: The type 'available' for presence does not actually appear in
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	117 the protocol. Available presence is signalled by the omission of a type.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	118 Similarly, a message stanza with no type is equivalent to one of type
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	119 'normal'. mod\_firewall handles these cases for you automatically.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	120
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	121 #### INSPECT
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	122
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	123 INSPECT takes a 'path' through the stanza to get a string (an attribute
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	124 value or text content). An example is the best way to explain. Let's
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	125 check that a user is not trying to register an account with the username
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	126 'admin'. This stanza comes from [XEP-0077: In-band
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	127 Registration](http://xmpp.org/extensions/xep-0077.html#example-4):
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	128
2002 ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	129 ``` xml
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	130 <iq type='set' id='reg2'>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	131 <query xmlns='jabber:iq:register'>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	132 <username>bill</username>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	133 <password>Calliope</password>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	134 <email>bard@shakespeare.lit</email>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	135 </query>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	136 </iq>
ce991c678370 mod_firewall/README: Markup XML example as XML :) Kim Alvefur <zash@zash.se> parents: 1803 diff changeset	137 ```
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	138
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	139 KIND: iq
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	140 TYPE: set
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	141 PAYLOAD: jabber:iq:register
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	142 INSPECT: {jabber:iq:register}query/username#=admin
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	143 BOUNCE=not-allowed The username 'admin' is reserved.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	144
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	145 That weird string deserves some explanation. It is a path, divided into
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	146 segments by '/'. Each segment describes an element by its name,
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	147 optionally prefixed by its namespace in curly braces ('{...}'). If the
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	148 path ends with a '\#' then the text content of the last element will be
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	149 returned. If the path ends with '@name' then the value of the attribute
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	150 'name' will be returned.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	151
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	152 INSPECT is somewhat slower than the other stanza matching conditions. To
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	153 minimise performance impact, always place it below other faster
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	154 condition checks where possible (e.g. above we first checked KIND, TYPE
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	155 and PAYLOAD matched before INSPECT).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	156
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	157 ### Sender/recipient matching
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	158
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	159 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	160 ----------- -------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	161 `FROM` The JID in the 'from' attribute matches the given JID
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	162 `TO` The JID in the 'to' attribute matches the given JID
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	163
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	164 These conditions both accept wildcards in the JID when the wildcard
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	165 expression is enclosed in angle brackets ('\<...\>'). For example:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	166
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	167 # All users at example.com
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	168 FROM: <*>@example.com
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	169
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	170 # The user 'admin' on any subdomain of example.com
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	171 FROM: admin@<*.example.com>
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	172
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	173 You can also use [Lua's pattern
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	174 matching](http://www.lua.org/manual/5.1/manual.html#5.4.1) for more
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	175 powerful matching abilities. Patterns are a lightweight
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	176 regular-expression alternative. Simply contain the pattern in double
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	177 angle brackets. The pattern is automatically anchored at the start and
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	178 end (so it must match the entire portion of the JID).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	179
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	180 # Match admin@example.com, and admin1@example.com, etc.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	181 FROM: <<admin%d*>>@example.com
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	182
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	183 Note: It is important to know that 'example.com' is a valid JID on
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	184 its own, and does not match 'user@example.com'. To perform domain
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	185 whitelists or blacklists, use Zones.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	186
2047 2ec7c0b8a371 mod_firewall/README: Fix table Kim Alvefur <zash@zash.se> parents: 2036 diff changeset	187 Condition Matches
2ec7c0b8a371 mod_firewall/README: Fix table Kim Alvefur <zash@zash.se> parents: 2036 diff changeset	188 ---------------- ---------------------------------------------------------------
2ec7c0b8a371 mod_firewall/README: Fix table Kim Alvefur <zash@zash.se> parents: 2036 diff changeset	189 `FROM_EXACTLY` The JID in the 'from' attribute exactly matches the given JID
2ec7c0b8a371 mod_firewall/README: Fix table Kim Alvefur <zash@zash.se> parents: 2036 diff changeset	190 `TO_EXACTLY` The JID in the 'to' attribute exactly matches the given JID
2036 7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	191
7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	192 These additional conditions do not support pattern matching, but are
7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	193 useful to match the exact to/from address on a stanza. For example, if
7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	194 no resource is specified then only bare JIDs will be matched. TO and FROM
7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	195 match all resources if no resource is specified to match.
7ba6ed553c93 mod_firewall/conditions: Add FROM_EXACTLY and TO_EXACTLY Matthew Wild <mwild1@gmail.com> parents: 2002 diff changeset	196
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	197 Note: Some chains execute before Prosody has performed any
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	198 normalisation or validity checks on the to/from JIDs on an incoming
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	199 stanza. It is not advisable to perform access control or similar rules
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	200 on JIDs in these chains (see the chain documentation for more info).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	201
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	202 ### Time and date
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	203
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	204 #### TIME
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	205
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	206 Matches stanzas sent during certain time periods.
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	207
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	208 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	209 ----------- -------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	210 TIME When the current server local time is within one of the comma-separated time ranges given
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	211
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	212 TIME: 10pm-6am, 14:00-15:00
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	213 REPLY=Zzzz.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	214
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	215 #### DAY
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	216
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	217 It is also possible to match only on certain days of the week.
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	218
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	219 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	220 ----------- -----------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	221 DAY When the current day matches one, or falls within a rage, in the given comma-separated list of days
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	222
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	223 Example:
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	224
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	225 DAY: Sat-Sun, Wednesday
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	226 REPLY=Sorry, I'm out enjoying life!
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	227
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	228 ### Rate-limiting
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	229
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	230 It is possible to selectively rate-limit stanzas, and use rules to
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	231 decide what to do with stanzas when over the limit.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	232
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	233 First, you must define any rate limits that you are going to use in your
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	234 script. Here we create a limiter called 'normal' that will allow 2
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	235 stanzas per second, and then we define a rule to bounce messages when
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	236 over this limit. Note that the `RATE` definition is not part of a rule
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	237 (multiple rules can share the same limiter).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	238
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	239 %RATE normal: 2 (burst 3)
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	240
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	241 KIND: message
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	242 LIMIT: normal
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	243 BOUNCE=policy-violation (Sending too fast!)
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	244
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	245 The 'burst' parameter on the rate limit allows you to spread the limit
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	246 check over a given time period. For example the definition shown above
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	247 will allow the limit to be temporarily surpassed, as long as it is
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	248 within the limit after 3 seconds. You will almost always want to specify
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	249 a burst factor.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	250
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	251 Both the rate and the burst can be fractional values. For example a rate
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	252 of 0.1 means only one event is allowed every 10 seconds.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	253
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	254 The LIMIT condition actually does two things; first it counts against
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	255 the given limiter, and then it checks to see if the limiter over its
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	256 limit yet. If it is, the condition matches, otherwise it will not.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	257
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	258 Condition Matches
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	259 ----------- --------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	260 `LIMIT` When the named limit is 'used up'. Using this condition automatically counts against that limit.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	261
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	262 Note: Reloading mod\_firewall resets the current state of any
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	263 limiters.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	264
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	265 Actions
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	266 -------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	267
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	268 Actions come after all conditions in a rule block. There must be at
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	269 least one action, though conditions are optional.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	270
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	271 An action without parameters ends with a full-stop/period ('.'), and one
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	272 with parameters uses an equals sign ('='):
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	273
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	274 # An action with no parameters:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	275 DROP.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	276
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	277 # An action with a parameter:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	278 REPLY=Hello, this is a reply.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	279
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	280 ### Route modification
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	281
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	282 The most common actions modify the stanza's route in some way. Currently
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	283 the first matching rule to do so will halt further processing of actions
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	284 and rules (this may change in the future).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	285
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	286 Action Description
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	287 ----------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	288 `PASS.` Stop executing actions and rules on this stanza, and let it through this chain.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	289 `DROP.` Stop executing actions and rules on this stanza, and discard it.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	290 `REDIRECT=jid` Redirect the stanza to the given JID.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	291 `REPLY=text` Reply to the stanza (assumed to be a message) with the given text.
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	292 `BOUNCE.` Bounce the stanza with the default error (usually service-unavailable)
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	293 `BOUNCE=error` Bounce the stanza with the given error (MUST be a defined XMPP stanza error, see [RFC6120](http://xmpp.org/rfcs/rfc6120.html#stanzas-error-conditions).
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	294 `BOUNCE=error (text)` As above, but include the supplied human-readable text with a description of the error
2092 f5d78bc016a6 mod_firewall: README: Add warning about COPY action's ability to cause loops (thanks Ge0rG) Matthew Wild <mwild1@gmail.com> parents: 2047 diff changeset	295 `COPY=jid` Make a copy of the stanza and send the copy to the specified JID. The copied stanza flows through Prosody's routing code, and as such is affected by firewall rules. Be careful to avoid loops.
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	296
2095 3b4a6d255d7a mod_firewall: README: Add note about BOUNCE and error stanzas/iq results Matthew Wild <mwild1@gmail.com> parents: 2093 diff changeset	297 Note: It is incorrect behaviour to reply to an 'error' stanza with another error, so BOUNCE will simply act the same as 'DROP' for stanzas that should not be bounced (error stanzas and iq results).
3b4a6d255d7a mod_firewall: README: Add note about BOUNCE and error stanzas/iq results Matthew Wild <mwild1@gmail.com> parents: 2093 diff changeset	298
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	299 ### Stanza modification
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	300
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	301 These actions make it possible to modify the content and structure of a
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	302 stanza.
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	303
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	304 Action Description
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	305 ------------------------ ------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	306 `STRIP=name` Remove any child elements with the given name in the default namespace
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	307 `STRIP=name namespace` Remove any child elements with the given name and the given namespace
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	308 `INJECT=xml` Inject the given XML into the stanza as a child element
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	309
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	310 ### Informational
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	311
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	312 Action Description
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	313 --------------- ------------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	314 `LOG=message` Logs the given message to Prosody's log file. Optionally prefix it with a log level in square brackets, e.g. `[debug]`
2093 7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	315
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	316 You can include expressions in log messages, using `$(...)` syntax. For example, to log the stanza that matched the rule, you can use $(stanza),
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	317 or to log just the top tag of the stanza, use $(stanza:top_tag()).
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	318
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	319 Example:
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	320
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	321 # Log all stanzas to user@example.com:
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	322 TO: user@example.com
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	323 LOG=[debug] User received: $(stanza)
7b9520479e99 mod_firewall: README: Document LOG's ability to take meta expressions Matthew Wild <mwild1@gmail.com> parents: 2092 diff changeset	324

Mercurial > prosody-modules

annotate mod_firewall/README.markdown @ 2095:3b4a6d255d7a