# HG changeset patch
# User MWild1@gmail.com
# Date 1365290894 0
# Node ID ecf8bfe998ec3a154f91ac48a05a449f0642e4d0
# Parent  53771c083c1971da06fda885ebed5a8f76324348
Add documentation on DAY, TIME, RATE and LIMIT firewall conditions

diff -r 53771c083c19 -r ecf8bfe998ec mod_firewall.wiki
--- 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.