From c7ad12177a03d2021fec9505e29e6dd380290491 Mon Sep 17 00:00:00 2001
From: Tom Eastep <teastep@shorewall.net>
Date: Fri, 12 Jul 2013 14:47:22 -0700
Subject: [PATCH] Enhance description of events by mentioning xt_recent
 options.

Signed-off-by: Tom Eastep <teastep@shorewall.net>
---
 docs/Events.xml | 66 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/docs/Events.xml b/docs/Events.xml
index 93cbf3d8b..270c26dfb 100644
--- a/docs/Events.xml
+++ b/docs/Events.xml
@@ -50,7 +50,7 @@
     <itemizedlist>
       <listitem>
         <para>Has event E ever occurred for IP address A (is the IP address in
-        the list)? </para>
+        the list)?</para>
       </listitem>
 
       <listitem>
@@ -103,6 +103,35 @@
         </listitem>
       </varlistentry>
     </variablelist>
+
+    <para>Events are based on the Netfilter 'recent match' capability which is
+    required for their use.</para>
+
+    <para>The recent-match kernel component is xt_recent which has two options
+    that are of interest to Shorewall users:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>ip_list_tot</term>
+
+        <listitem>
+          <para>The number of addresses remembered per event. Default is
+          100.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ip_pkt_list_tot</term>
+
+        <listitem>
+          <para>The number of packets (event occurrences) remembered per
+          address. Default is 20.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>These may be changed with the xt_recent module is loaded or on the
+    kernel bootloader runline.</para>
   </section>
 
   <section>
@@ -380,6 +409,41 @@
         </varlistentry>
       </variablelist>
     </section>
+
+    <section>
+      <title>'show event' and 'show events' Commands</title>
+
+      <para>The CLI programs (<filename>/sbin/shorewall</filename>,
+      <filename>/sbin/shorewall-lite</filename>, etc.) support <command>show
+      event</command> and <command>show events</command> commands.</para>
+
+      <para>The <command>show event</command> command shows the contents of
+      the events listed in the command while <emphasis role="bold">show
+      events</emphasis> lists the contents of all events.</para>
+
+      <programlisting>root@gateway:~# shorewall show events
+Shorewall 4.5.19-Beta2 events at gateway - Fri Jul 12 13:21:27 PDT 2013
+
+Current time: 4404787304 <emphasis role="bold">&lt;================ Times are 'milliseconds since boot'</emphasis>
+
+SSH <emphasis role="bold">&lt;================= This and the next event are created by the Autoblacklist example below</emphasis>
+src=125.46.13.163 ttl: 114 last_seen: 4403672214 oldest_pkt: 1 4403672214
+src=200.59.55.50 ttl: 32 last_seen: 4403225346 oldest_pkt: 2 4403225096, 4403225346
+src=65.182.111.112 ttl: 118 last_seen: 4404178828 oldest_pkt: 1 4404178828
+
+SSH_COUNTER <emphasis role="bold">&lt;====================== This event has not occurred recently.</emphasis>
+
+sticky001 <emphasis role="bold">&lt;================== This and the next events are generated by the Shorewall SAME rule target.</emphasis>
+src=172.20.1.146 ttl: 64 last_seen: 4404774586 oldest_pkt: 9 4404731690, 4404731690, 4404731690, 4404731690, 4404731690, 4404731691, 4404750647, 4404774560, 4404774586, 4404731667, 4404731667, 4404731669, 4404731669, 4404731669, 4404731669, 4404731669, 4404731669, 4404731688, 4404731689, 4404731689
+
+sticky002
+src=172.20.1.213 ttl: 128 last_seen: 4404785474 oldest_pkt: 6 4404785172, 4404785215, 4404785324, 4404785397, 4404785407, 4404785474, 4404767925, 4404767925, 4404767925, 4404767942, 4404768011, 4404768011, 4404768011, 4404768012, 4404768014, 4404768014, 4404768042, 4404768042, 4404768042, 4404768043
+
+root@gateway:~# </programlisting>
+
+      <para>Note that the times of the recent events are recorded for each
+      address.</para>
+    </section>
   </section>
 
   <section>