author | Kim Alvefur <zash@zash.se> |
Wed, 07 Oct 2015 20:41:20 +0200 | |
changeset 1901 | effd909d05b0 |
parent 1807 | 4d73a1a6ba68 |
child 2006 | ce991c678370 |
permissions | -rw-r--r-- |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
1 |
--- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
2 |
labels: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
3 |
- 'Stage-Alpha' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
4 |
summary: 'A rule-based stanza filtering module' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
5 |
... |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
6 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
7 |
------------------------------------------------------------------------ |
1786 | 8 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
12 |
at the bottom of this page. |
1786 | 13 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
14 |
------------------------------------------------------------------------ |
1786 | 15 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
16 |
Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
17 |
============ |
1786 | 18 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
22 |
rules. |
1786 | 23 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
28 |
server. |
1786 | 29 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
30 |
Details |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
31 |
======= |
1786 | 32 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
35 |
syntax is unusual, but straightforward. |
1786 | 36 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
39 |
all of the actions are executed in order. |
1786 | 40 |
|
41 |
Here is a simple example to block stanzas from spammer@example.com: |
|
42 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
43 |
FROM: spammer@example.com |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
44 |
DROP. |
1786 | 45 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
48 |
something more complex that mod\_firewall can do for you: |
1786 | 49 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
50 |
%ZONE myorganisation: staff.myorg.example, support.myorg.example |
1786 | 51 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
52 |
ENTERING: myorganisation |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
53 |
KIND: message |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
54 |
TIME: 12am-9am, 5pm-12am, Saturday, Sunday |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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. |
1786 | 56 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
59 |
outside of office hours. |
1786 | 60 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
63 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
64 |
firewall_scripts = { "path/to/ruleset.pfw" } |
1786 | 65 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
66 |
Conditions |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
67 |
---------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
68 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
70 |
condition name is followed by a colon (':'), and the value to test for. |
1786 | 71 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
73 |
For example: |
1786 | 74 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
75 |
NOT FROM: user@example.com |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
76 |
KIND NOT: message |
1786 | 77 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
78 |
### Zones |
1786 | 79 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
82 |
matching traffic passing between JIDs in the same zone. |
1786 | 83 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
85 |
are not part of a rule block): |
1786 | 86 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
87 |
%ZONE myzone: host1, host2, user@host3, foo.bar.example |
1786 | 88 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
90 |
subdomains). |
1786 | 91 |
|
92 |
The following zone-matching conditions are supported: |
|
93 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
94 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
95 |
------------ ------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
97 |
`LEAVING` When a stanza is leaving the named zone |
1786 | 98 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
99 |
### Stanza matching |
1786 | 100 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
101 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
102 |
----------- ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
107 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
108 |
#### Stanza types |
1786 | 109 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
110 |
Stanza Valid types |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
111 |
---------- ------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
112 |
iq get, set, result, error |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
114 |
message normal, chat, groupchat, headline, error |
1786 | 115 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
119 |
'normal'. mod\_firewall handles these cases for you automatically. |
1786 | 120 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
121 |
#### INSPECT |
1786 | 122 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
127 |
Registration](http://xmpp.org/extensions/xep-0077.html#example-4): |
1786 | 128 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
129 |
<iq type='set' id='reg2'> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
130 |
<query xmlns='jabber:iq:register'> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
131 |
<username>bill</username> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
132 |
<password>Calliope</password> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
133 |
<email>bard@shakespeare.lit</email> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
134 |
</query> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
135 |
</iq> |
1786 | 136 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
137 |
KIND: iq |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
138 |
TYPE: set |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
139 |
PAYLOAD: jabber:iq:register |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
140 |
INSPECT: {jabber:iq:register}query/username#=admin |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
141 |
BOUNCE=not-allowed The username 'admin' is reserved. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
142 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
143 |
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:
1786
diff
changeset
|
144 |
segments by '/'. Each segment describes an element by its name, |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
145 |
optionally prefixed by its namespace in curly braces ('{...}'). If the |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
146 |
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:
1786
diff
changeset
|
147 |
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:
1786
diff
changeset
|
148 |
'name' will be returned. |
1786 | 149 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
150 |
INSPECT is somewhat slower than the other stanza matching conditions. To |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
151 |
minimise performance impact, always place it below other faster |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
152 |
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:
1786
diff
changeset
|
153 |
and PAYLOAD matched before INSPECT). |
1786 | 154 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
155 |
### Sender/recipient matching |
1786 | 156 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
157 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
158 |
----------- ------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
159 |
`FROM` The JID in the 'from' attribute matches the given JID |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
160 |
`TO` The JID in the 'to' attribute matches the given JID |
1786 | 161 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
162 |
These conditions both accept wildcards in the JID when the wildcard |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
163 |
expression is enclosed in angle brackets ('\<...\>'). For example: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
164 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
165 |
# All users at example.com |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
166 |
FROM: <*>@example.com |
1786 | 167 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
168 |
# The user 'admin' on any subdomain of example.com |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
169 |
FROM: admin@<*.example.com> |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
170 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
171 |
You can also use [Lua's pattern |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
172 |
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:
1786
diff
changeset
|
173 |
powerful matching abilities. Patterns are a lightweight |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
174 |
regular-expression alternative. Simply contain the pattern in double |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
175 |
angle brackets. The pattern is automatically anchored at the start and |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
176 |
end (so it must match the entire portion of the JID). |
1786 | 177 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
178 |
# Match admin@example.com, and admin1@example.com, etc. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
179 |
FROM: <<admin%d*>>@example.com |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
180 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
181 |
**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:
1786
diff
changeset
|
182 |
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:
1786
diff
changeset
|
183 |
whitelists or blacklists, use Zones. |
1786 | 184 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
185 |
**Note:** Some chains execute before Prosody has performed any |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
186 |
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:
1786
diff
changeset
|
187 |
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:
1786
diff
changeset
|
188 |
on JIDs in these chains (see the chain documentation for more info). |
1786 | 189 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
190 |
### Time and date |
1786 | 191 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
192 |
#### TIME |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
193 |
|
1786 | 194 |
Matches stanzas sent during certain time periods. |
195 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
196 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
197 |
----------- ------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
198 |
TIME When the current server local time is within one of the comma-separated time ranges given |
1786 | 199 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
200 |
TIME: 10pm-6am, 14:00-15:00 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
201 |
REPLY=Zzzz. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
202 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
203 |
#### DAY |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
204 |
|
1786 | 205 |
It is also possible to match only on certain days of the week. |
206 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
207 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
208 |
----------- ----------------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
209 |
DAY When the current day matches one, or falls within a rage, in the given comma-separated list of days |
1786 | 210 |
|
211 |
Example: |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
212 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
213 |
DAY: Sat-Sun, Wednesday |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
214 |
REPLY=Sorry, I'm out enjoying life! |
1786 | 215 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
216 |
### Rate-limiting |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
217 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
218 |
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:
1786
diff
changeset
|
219 |
decide what to do with stanzas when over the limit. |
1786 | 220 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
221 |
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:
1786
diff
changeset
|
222 |
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:
1786
diff
changeset
|
223 |
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:
1786
diff
changeset
|
224 |
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:
1786
diff
changeset
|
225 |
(multiple rules can share the same limiter). |
1786 | 226 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
227 |
%RATE normal: 2 (burst 3) |
1786 | 228 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
229 |
KIND: message |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
230 |
LIMIT: normal |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
231 |
BOUNCE=policy-violation (Sending too fast!) |
1786 | 232 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
233 |
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:
1786
diff
changeset
|
234 |
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:
1786
diff
changeset
|
235 |
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:
1786
diff
changeset
|
236 |
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:
1786
diff
changeset
|
237 |
a burst factor. |
1786 | 238 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
239 |
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:
1786
diff
changeset
|
240 |
of 0.1 means only one event is allowed every 10 seconds. |
1786 | 241 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
242 |
The LIMIT condition actually does two things; first it counts against |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
243 |
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:
1786
diff
changeset
|
244 |
limit yet. If it is, the condition matches, otherwise it will not. |
1786 | 245 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
246 |
Condition Matches |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
247 |
----------- -------------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
248 |
`LIMIT` When the named limit is 'used up'. Using this condition automatically counts against that limit. |
1786 | 249 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
250 |
**Note:** Reloading mod\_firewall resets the current state of any |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
251 |
limiters. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
252 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
253 |
Actions |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
254 |
------- |
1786 | 255 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
256 |
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:
1786
diff
changeset
|
257 |
least one action, though conditions are optional. |
1786 | 258 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
259 |
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:
1786
diff
changeset
|
260 |
with parameters uses an equals sign ('='): |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
261 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
262 |
# An action with no parameters: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
263 |
DROP. |
1786 | 264 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
265 |
# An action with a parameter: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
266 |
REPLY=Hello, this is a reply. |
1786 | 267 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
268 |
### Route modification |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
269 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
270 |
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:
1786
diff
changeset
|
271 |
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:
1786
diff
changeset
|
272 |
and rules (this may change in the future). |
1786 | 273 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
274 |
Action Description |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
275 |
----------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
276 |
`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:
1786
diff
changeset
|
277 |
`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:
1786
diff
changeset
|
278 |
`REDIRECT=jid` Redirect the stanza to the given JID. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
279 |
`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:
1786
diff
changeset
|
280 |
`BOUNCE.` Bounce the stanza with the default error (usually service-unavailable) |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
281 |
`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:
1786
diff
changeset
|
282 |
`BOUNCE=error (text)` As above, but include the supplied human-readable text with a description of the error |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
283 |
`COPY=jid` Make a copy of the stanza and send the copy to the specified JID. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
284 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
285 |
### Stanza modification |
1786 | 286 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
287 |
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:
1786
diff
changeset
|
288 |
stanza. |
1786 | 289 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
290 |
Action Description |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
291 |
------------------------ ------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
292 |
`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:
1786
diff
changeset
|
293 |
`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:
1786
diff
changeset
|
294 |
`INJECT=xml` Inject the given XML into the stanza as a child element |
1786 | 295 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
296 |
### Informational |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
297 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
298 |
Action Description |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
299 |
--------------- ------------------------------------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
300 |
`LOG=message` Logs the given message to Prosody's log file. Optionally prefix it with a log level in square brackets, e.g. `[debug]` |