changeset 340:ecf8bfe998ec

Add documentation on DAY, TIME, RATE and LIMIT firewall conditions
author MWild1@gmail.com
date Sat, 06 Apr 2013 23:28:14 +0000
parents 53771c083c19
children 206f6bf2356c
files mod_firewall.wiki
diffstat 1 files changed, 48 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/mod_firewall.wiki	Sat Apr 06 16:58:47 2013 +0000
+++ b/mod_firewall.wiki	Sat Apr 06 23:28:14 2013 +0000
@@ -131,6 +131,54 @@
 
 *Note:* Some chains execute before Prosody has performed any normalisation or validity checks on the to/from JIDs on an incoming stanza. It is not advisable to perform access control or similar rules on JIDs in these chains (see the chain documentation for more info).
 
+=== Time and date ===
+==== TIME ====
+Matches stanzas sent during certain time periods.
+|| *Condition* || *Matches* ||
+|| TIME || When the current server local time is within one of the comma-separated time ranges given ||
+
+{{{
+TIME: 10pm-6am, 14:00-15:00
+REPLY=Zzzz.
+}}}
+
+==== DAY ====
+It is also possible to match only on certain days of the week.
+
+|| *Condition* || *Matches* ||
+|| DAY || When the current day matches one, or falls within a rage, in the given comma-separated list of days ||
+
+Example:
+{{{
+DAY: Sat-Sun, Wednesday
+REPLY=Sorry, I'm out enjoying life!
+}}}
+
+
+=== Rate-limiting ===
+It is possible to selectively rate-limit stanzas, and use rules to decide what to do with stanzas when over the limit.
+
+First, you must define any rate limits that you are going to use in your script. Here we create a limiter called 'normal' that will allow 2 stanzas per second, and then we define a rule to bounce messages when over this limit. Note that the `RATE` definition is not part of a rule (multiple rules can share the same limiter).
+
+{{{
+RATE normal: 2 (burst 3)
+
+KIND: message
+LIMIT: normal
+BOUNCE=policy-violation (Sending too fast!)
+}}}
+
+The 'burst' parameter on the rate limit allows you to spread the limit check over a given time period. For example the definition shown above will allow the limit to be temporarily surpassed, as long as it is within the limit after 3 seconds. You will almost always want to specify a burst factor.
+
+Both the rate and the burst can be fractional values. For example a rate of 0.1 means only one event is allowed every 10 seconds.
+
+The LIMIT condition actually does two things; first it counts against the given limiter, and then it checks to see if the limiter over its limit yet. If it is, the condition matches, otherwise it will not.
+
+|| *Condition* || *Matches* ||
+|| `LIMIT` || When the named limit is 'used up'. Using this condition automatically counts against that limit. ||
+
+*Note:* Reloading mod_firewall resets the current state of any limiters.
+
 == Actions ==
 Actions come after all conditions in a rule block. There must be at least one action, though conditions are optional.