diff --git a/docs/Events.xml b/docs/Events.xml
index 41c4cf8d3..8cd2f21ec 100644
--- a/docs/Events.xml
+++ b/docs/Events.xml
@@ -457,6 +457,10 @@ root@gateway:/usr/src/linux-source-3.2/net/netfilter#
but the system where this example was captured used the default value of
the ip_pkt_list_tot xt_recent option
(20).
+
+ The output of these commands is produced by processing the
+ contents of /proc/net/xt_recent/*. You can access
+ those files directly to see the raw data.
diff --git a/docs/Events1.xml b/docs/Events1.xml
new file mode 100644
index 000000000..5e5f7da46
--- /dev/null
+++ b/docs/Events1.xml
@@ -0,0 +1,592 @@
+
+
+
+
+
+
+ Shorewall Events
+
+
+
+ Tom
+
+ Eastep
+
+
+
+
+
+
+ 2013
+
+ Thomas M. Eastep
+
+
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License, Version
+ 1.2 or any later version published by the Free Software Foundation; with
+ no Invariant Sections, with no Front-Cover, and with no Back-Cover
+ Texts. A copy of the license is included in the section entitled
+ GNU Free Documentation
+ License
.
+
+
+
+
+ This article applies to Shorewall 4.5.19 and later and supercedes
+ this article.
+
+
+
+ Overview
+
+ Shorewall events were introduced in Shorewall 4.5.19 and provide a
+ high-level interface to the Netfilter recent match
+ capability. An event is actually a list of (IP address, timestamp) pairs,
+ and can be tested in a number of different ways:
+
+
+
+ Has event E ever occurred for IP address A (is the IP address in
+ the list)?
+
+
+
+ Has event E occurred M or more times for IP address A?
+
+
+
+ Has Event E occurred in the last N seconds for IP Address A (is
+ there an entry for the address with a timestamp falling within the
+ last N seconds)?
+
+
+
+ Has Event E occurred M or more times in the last N seconds for
+ IP address A (are there M or more entries for the address with
+ timestamps falling within the last N seconds)?
+
+
+
+ The event interface is implemented as three parameterized Shorewall
+ Actions:
+
+
+
+ SetEvent
+
+
+ This action initializes an event list for either the source or
+ destination IP address in the current packets. The list will contain
+ a single entry for the address that will have the current
+ timestamp.
+
+
+
+
+ ResetEvent
+
+
+ This action removes all entries for either the source or
+ destination IP address from an event list.
+
+
+
+
+ IfEvent
+
+
+ This action tests an event in one of the ways listed above,
+ and performs an action based on the result.
+
+
+
+
+ Events are based on the Netfilter 'recent match' capability which is
+ required for their use.
+
+ The recent-match kernel component is xt_recent which has two options
+ that are of interest to Shorewall users:
+
+
+
+ ip_list_tot
+
+
+ The number of addresses remembered per event. Default is
+ 100.
+
+
+
+
+ ip_pkt_list_tot
+
+
+ The number of packets (event occurrences) remembered per
+ address. Default is 20.
+
+
+
+
+ These may be changed with the xt_recent module is loaded or on the
+ kernel bootloader runline.
+
+
+
+ Details
+
+ Because these are parameterized actions, optional parameters may be
+ omitted. Trailing omitted parameters may be omitted entirely while
+ embedded omitted parameters are represented by a hyphen ("-").
+
+ Each event is given a name. Event names:
+
+
+
+ Must begin with a letter.
+
+
+
+ May be composed of letters, digits, hyphens ('-') or underscores
+ ('_').
+
+
+
+ May be at most 29 characters in length.
+
+
+
+
+ SetEvent
+
+ SetEvent(
+ event, [ action ],
+ [ src-dst ], [
+ disposition ] )
+
+
+
+ event
+
+
+ Name of the event.
+
+
+
+
+ action
+
+
+ An action to perform after the event is initialized. May be
+ any action that may appear in the ACTION column of shorewall-rules (5).
+ If no action is to be performed, use COUNT.
+
+
+
+
+ src-dst
+
+
+ Specifies whether the source IP address (src) or destination IP address (dst) is to be added to the event. The
+ default is src.
+
+
+
+
+ disposition
+
+
+ If the action involves logging,
+ then this parameter specifies the disposition that will appear in
+ the log entry prefix. If no disposition
+ is given, the log prefix is determines normally. The default is
+ ACCEPT.
+
+
+
+
+
+
+ ResetEvent
+
+ ResetEvent(
+ event, [ action ],
+ [ src-dst ], [
+ disposition ] )
+
+
+
+ event
+
+
+ Name of the event.
+
+
+
+
+ action
+
+
+ An action to perform after the event is reset. May be any
+ action that may appear in the ACTION column of shorewall-rules (5).
+ If no action is to be performed, use COUNT. The default is
+ ACCEPT.
+
+
+
+
+ src-dst
+
+
+ Specifies whether the source IP address (src) or destination IP address (dst) is to be removed from the event. The
+ default is src.
+
+
+
+
+ disposition
+
+
+ If the action involves logging,
+ then this parameter specifies the disposition that will appear in
+ the log entry prefix. If no disposition
+ is given, the log prefix is determines normally.
+
+
+
+
+
+
+ IfEvent
+
+ IfEvent(
+ event, [ action ],
+ [ duration ], [
+ hitcount ], [
+ src-dst], [
+ command ], [
+ disposition ] )
+
+
+
+ event
+
+
+ Name of the event.
+
+
+
+
+ action
+
+
+ An action to perform if the test succeeds. May be any action
+ that may appear in the ACTION column of shorewall-rules (5).
+ The default is ACCEPT.
+
+
+
+
+ duration
+
+
+ Number of seconds over which the event is to be tested. If
+ not specified, the test is not constrained by time.
+
+
+
+
+ hitcount
+
+
+ Specifies the minimum number of packets required for the
+ test to succeed. If not specified, 1 packet is assumed.
+
+
+
+
+ src-dst
+
+
+ Specifies whether the source IP address (src) or destination IP address (dst) is to be tested. The default is
+ src.
+
+
+
+
+ command
+
+
+ May be one of the following:
+
+
+
+ check
+
+
+ Simply test if the
+ duration/hitcount
+ test is satisfied. If so, the
+ action is performed.
+
+
+
+
+ reset
+
+
+ Like check. If the
+ test succeeds, the event will be
+ reset before the action is
+ taken.
+
+
+
+
+ update
+
+
+ Like check.
+ Regardless of whether the test succeeds, an entry with the
+ current time and for the src-dst
+ iP address will be added to the
+ event.
+
+
+
+
+ checkreap
+
+
+ Requires a duration. Like
+ check but regardless of
+ whether the test succeeds, entries for the
+ src-dst IP address that are older
+ than duration seconds will be
+ deleted from the event.
+
+
+
+
+ updatereap
+
+
+ Requires a duration. Like
+ update but regardless of
+ whether the test succeeds, entries for the
+ src-dst IP address that are older
+ than duration seconds will be
+ deleted from the event.
+
+
+
+
+ The default is check.
+
+
+
+
+ disposition
+
+
+ If the action involves logging,
+ then this parameter specifies the disposition that will appear in
+ the log entry prefix. If no disposition
+ is given, the log prefix is determines normally.
+
+
+
+
+
+
+ 'show event' and 'show events' Commands
+
+ The CLI programs (/sbin/shorewall,
+ /sbin/shorewall-lite, etc.) support show
+ event and show events commands.
+
+ The show event command shows the contents of
+ the events listed in the command while show
+ events lists the contents of all events.
+
+ root@gateway:/usr/src/linux-source-3.2/net/netfilter# shorewall show events
+Shorewall 4.5.19-Beta2 events at gateway - Fri Jul 12 15:57:20 PDT 2013
+
+SSH
+ src=125.46.13.163 : 3453
+ src=200.59.55.50 : 3900 3900
+ src=65.182.111.112 : 2946
+
+SSH_COUNTER
+
+sticky001
+ src=172.20.1.146 : 8 8 8 8 8 8 8 8 8 8 8 8 8 8 7 7 7 7 7 7
+
+sticky002
+ src=172.20.1.213 : 53 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 46 46
+
+root@gateway:/usr/src/linux-source-3.2/net/netfilter#
+
+ The SSH and SSH_COUNTER events are created using the following
+ Automatic Blacklisting example. The sticky001 and sticky002 events are
+ created by the SAME rule action.
+
+ Each line represents one event. The list of numbers following the
+ ':' represent the number of seconds ago that a matching packet triggered
+ the event. The numbers are in chronological sequence, so In this event,
+ there were 20 packets from 172.20.1.213 that arrived between 53 and 46
+ seconds ago:
+
+ sticky002
+ src=172.20.1.213 : 53 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 46 46
+
+ Note that there may have been earlier packets that also matched,
+ but the system where this example was captured used the default value of
+ the ip_pkt_list_tot xt_recent option
+ (20).
+
+ The output of these commands is produced by processing the
+ contents of /proc/net/xt_recent/*. You can access
+ those files directly to see the raw data. Additional about these files
+ may be found in iptables (8).
+
+
+
+
+ Examples
+
+
+ Automatic Blacklisting
+
+ This example is taken from this
+ article which explains the nice benifits of this approach. This
+ example is for ssh, but it can be adapted for any application.
+
+ The name SSH has been changed to SSHLIMIT so as not to override
+ the Shorewall macro of the same name.
+
+ /etc/shorewall/actions:
+
+ #ACTION OPTION DESCRIPTION
+SSHLIMIT #Automatically blacklist hosts who exceed SSH connection limits
+
+
+ /etc/shorewall/action.SSH_BLACKLIST:
+
+ #
+# Shorewall version 4 - SSH_BLACKLIST Action
+#
+?format 2
+###############################################################################
+#TARGET SOURCE DEST PROTO DPORT SPORT
+#
+# Log the Reject
+#
+LOG:warn:REJECT
+#
+# And set the SSH_COUNTER event for the SOURCE IP address
+#
+SetEvent(SSH_COUNTER,REJECT,src)
+
+ /etc/shorewall/action.SSHLIMIT:
+
+ #
+# Shorewall version 4 - SSHLIMIT Action
+#
+?format 2
+###############################################################################
+#TARGET SOURCE DEST PROTO DPORT SPORT
+#
+# Silently reject the client if blacklisted
+#
+IfEvent(SSH_COUNTER,REJECT,300,1)
+#
+# Blacklist if 5 attempts in the last minute
+#
+IfEvent(SSH,SSH_BLACKLIST,60,5,src,checkreap)
+#
+# Log and reject if the client has tried to connect
+# in the last two seconds
+#
+IfEvent(SSH,REJECT:warn:,2,1,-,update,Added)
+#
+# Un-blacklist the client
+#
+ResetEvent(SSH_COUNTER,LOG:warn,-,Removed)
+#
+# Set the 'SSH' EVENT and accept the connection
+#
+SetEvent(SSH,ACCEPT,src)
+
+ etc/shorewall/rules:
+
+ #ACTION SOURCE DEST PROTO DEST
+# PORT(S)
+SSHLIMIT net $FW tcp 22
+
+
+
+ Port Knocking
+
+ This example shows a different implementation of the one shown in
+ the Port Knocking article.
+
+ In this example:
+
+
+
+ Attempting to connect to port 1600 enables SSH access. Access
+ is enabled for 60 seconds.
+
+
+
+ Attempting to connect to port 1601 disables SSH access (note
+ that in the article linked above, attempting to connect to port 1599
+ also disables access. This is an port scan defence as explained in
+ the article).
+
+
+
+ To implement that approach:
+
+ /etc/shorewall/actions:
+
+ #ACTION OPTION DESCRIPTION
+Knock #Port Knocking
+
+ /etc/shorewall/action.Knock:
+
+ #
+# Shorewall version 4 - SSH_BLACKLIST Action
+#
+?format 2
+###############################################################################
+#ACTION SOURCE DEST PROTO DEST
+# PORT(S)
+IfEvent(SSH,ACCEPT:info,60,1,src,reset)\
+ - - tcp 22
+SetEvent(SSH,ACCEPT) - - tcp 1600
+ResetEvent(SSH,DROP:info)
+
+ etc/shorewall/rules:
+
+ #ACTION SOURCE DEST PROTO DEST
+# PORT(S)
+Knock net $FW tcp 22,1599-1601
+
+
+