Documentation of the counter stuff.

Signed-off-by: Florent Bruneau <florent.bruneau@polytechnique.org>

diff --git a/example/postlicyd.conf b/example/postlicyd.conf
index 6f3d07f..c5773b3 100644 (file)
--- a/example/postlicyd.conf
+++ b/example/postlicyd.conf
@@ -56,6 +56,16 @@
 #   A filter can returns different values. Each return value is given a name. The
 #   configuration associates an action to run to a return value name.
 #
+#   A hook action has the format: (counter:id:incr:)?(filter_name|postfix:ACTION)
+#
+#   The action can contains the reference to a counter to update. This counters are "message"-wide
+#   counters that stay valid until the end of the filtering of the message. This counters are useful
+#   to trig different actions depending on the number of failures encountered during the processing
+#   of a message. There are 64 counters (0..63), accessible from all the filters. By specifying
+#   counter:id:incr as a prefix of the hook action, you tell postlicyd to add (incr) to counter
+#   (id) when this hook is reached. The "counter" filter type allow you to run actions depending
+#   on the value of a counter.
+#
 #   The action can be either a postfix access(5) value or a filter name. Postfix access
 #   parameters must be prefixed by 'postfix:'. The text argument given to a postfix reply
 #   may contain format strings to be replaced by the parameters of the query. This arguments
@@ -64,6 +74,8 @@
 # eg:
 #   on_match = postfix:REJECT Blacklisted;
 #   on_fail  = postfix:450 Greylisted, see http://www.example.org/${sender_domain}.html
+#   on_error = counter:0:1:postfix:DUNNO
+#   on_match = counter:63:10:whitelist
 #
 # Filter:
 #   Current defined filter types are:
@@ -258,10 +270,35 @@ match {
 
   # hook
   on_match = postfix:OK;
-  on_fail = greylist;
+  on_fail = counter:0:1:greylist;
 }
 
 
+#    - counter: trig actions depending on the value of a counter
+#       Parameters:
+#          - counter: the id of the counter to trig on (0 -> 63)
+#          - hard_threshold: minimum counter value to trig the hard_match hook
+#          - soft_threshold: minimum counter value to trig the soft_match hook
+#       Return value:
+#          - hard_match if the counter with the given id is greater or equal to hard_threshold
+#          - soft_match if the counter value is between soft_threshold and hard_threshold
+#          - fail if the counter value is below soft_match
+
+# match if the counter 0 value is greater than 8, or between 5 and 7
+counter {
+  type = counter;
+
+  # configuration
+  counter        = 0;
+  hard_threshold = 8;
+  soft_threshold = 5;
+
+  # hook
+  on_hard_match = postfix:REJECT ${sender_domain};
+  on_soft_match = greylist;
+  on_fail       = counter:1:10:match;
+}
+
 # ENTRY POINTS
 #
 # Access policy daemon can be used at several protocol states. For each of this states,