diff --git a/Shorewall-docs2/Actions.xml b/Shorewall-docs2/Actions.xml
new file mode 100644
index 000000000..8a0dd98db
--- /dev/null
+++ b/Shorewall-docs2/Actions.xml
@@ -0,0 +1,503 @@
+
+
+
+
+
+
+ Actions
+
+
+
+ Tom
+
+ Eastep
+
+
+
+ 2005-01-19
+
+
+ 2005
+
+ 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
.
+
+
+
+
+ What are Shorewall Actions?
+
+ Shorewall actions allow a symbolic name to be associated with a
+ series of one or more iptables rules. The symbolic name may appear in the
+ ACTION column of an /etc/shorewall/rules file
+ entry in which case, the traffic matching that rules file entry will be
+ passed to the series of iptables rules named by the action.
+
+ Actions can be thought of as templates. When an action is invoked in
+ an /etc/shorewall/rules entry, it may be qualified by
+ a logging specification (log level and optionally a log tag). The presence
+ of the log level/tag causes a modified series of rules to be generated in
+ which each packet/rule match within the action causes a log message to be
+ generated.
+
+ There are three types of Shorewall actions:
+
+
+
+ Built-in Actions. These actions are known by the Shorewall code
+ itself. They are listed in the comments at the top of the file
+ /usr/share/shorewall/actions.std.
+
+
+
+ Standard Actions. These actions are released as part of
+ Shorewall. They are listed in the file
+ /usr/share/shorewall/actions.std and are defined
+ in the corresponding action.* files in /usr/share/shorewall. Each
+ action.* file has a comment at the beginning of
+ the file that describes what the action does. As an example, here is
+ the definition of the AllowSMB standard
+ action.
+
+ #
+# Shorewall 2.2 /usr/share/shorewall/action.AllowSMB
+#
+# Allow Microsoft SMB traffic. You need to invoke this action in
+# both directions.
+#
+######################################################################################
+#TARGET SOURCE DEST PROTO DEST SOURCE RATE USER/
+# PORT PORT(S) LIMIT GROUP
+ACCEPT - - udp 135,445
+ACCEPT - - udp 137:139
+ACCEPT - - udp 1024: 137
+ACCEPT - - tcp 135,139,445
+#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+ If you wish to modify one of the standard actions, do not modify
+ the definition in /usr/share/shorewall. Rather, copy the file to
+ /etc/shorewall (or somewhere
+ else on your CONFIG_PATH) and modify the copy.
+
+
+
+ User-defined Actions. These actions are created by end-users.
+ They are listed in the file /etc/shorewall/actions and are defined in
+ action.* files in /etc/shorewall/actions or in another directory
+ listed in your CONFIG_PATH (defined in /etc/shorewall/shorewall.conf).
+
+
+
+
+
+ Common Actions
+
+ Shorewall allows the association of a common
+ action with policies. A separate common action may be
+ associated with ACCEPT, DROP and REJECT policies. Common actions provide a
+ way to invoke a set of common rules just before the policy is enforced.
+ Common actions accomplish two goals:
+
+
+
+ Relieve log congestion. Common actions typically include rules
+ to silently drop or reject traffic that would otherwise be logged when
+ the policy is enforced.
+
+
+
+ Ensure correct operation. Common actions can also avoid common
+ pitfalls like dropping connection requests on port TCP port 113. If
+ these connections are dropped (rather than rejected) then you may
+ encounter problems connecting to internet services that utilize the
+ AUTH protocol of client authentication
+ AUTH is actually pretty silly on today's internet but it's
+ amazing how many servers still employ it.
+ .
+
+
+
+ Shorewall provides common actions for the REJECT and DROP policies.
+ The common action for REJECT is named Reject and
+ the common action for DROP is named Drop. These
+ associations are made through two entries in
+ /usr/share/shorewall/actions.std:
+
+ Drop:DROP #Common Action for DROP policy
+Reject:REJECT #Common Action for REJECT policy
+
+ These may be overridden by entries in your /etc/shorewall/actions
+ file.
+
+
+ Entries in the DROP and REJECT common actions ARE NOT THE CAUSE OF CONNECTION PROBLEMS.
+ Remember — common actions are only invoked immediately before the packet
+ is going to be dropped or rejected anyway!!!
+
+
+
+
+ User-defined Actions.
+
+ To define a new action:
+
+
+
+ Add a line to
+ /etc/shorewall/actions that
+ names your new action. Action names must be valid shell variable names
+ ((must begin with a letter and be composed of letters, digits and
+ underscore characters) as well as valid Netfilter chain names. If you
+ intend to log from the action, the name must have a maximum of 11
+ characters. It is recommended that the name you select for a new
+ action begins with with a capital letter; that way, the name won't
+ conflict with a Shorewall-defined chain name.
+
+ Beginning with Shorewall-2.0.0-Beta1, the name of the action may
+ be optionally followed by a colon (:
) and ACCEPT, DROP
+ or REJECT. When this is done, the named action will become the
+ common action for policies of type ACCEPT, DROP
+ or REJECT respectively. The common action is applied immediately
+ before the policy is enforced (before any logging is done under that
+ policy) and is used mainly to suppress logging of uninteresting
+ traffic which would otherwise clog your logs. The same policy name can
+ appear in multiple actions; the last such action for each policy name
+ is the one which Shorewall will use.
+
+ Shorewall includes pre-defined actions for DROP and REJECT --
+ see above.
+
+
+
+ Once you have defined your new action name (ActionName), then
+ copy /usr/share/shorewall/action.template to
+ /etc/shorewall/action.ActionName (for example, if
+ your new action name is Foo
then copy
+ /usr/share/shorewall/action.template to
+ /etc/shorewall/action.Foo).
+
+
+
+ Now modify the new file to define the new action.
+
+
+
+ Columns in the action.template file are as follows:
+
+
+
+ TARGET - Must be ACCEPT, DROP, REJECT, LOG, CONTINUE, QUEUE or
+ <action> where
+ <action> is a previously-defined action
+ (that is, it must precede the action being defined in this file in
+ your /etc/shorewall/actions file). These actions
+ have the same meaning as they do in the
+ /etc/shorewall/rules file (CONTINUE terminates
+ processing of the current action and returns to the point where that
+ action was invoked). The TARGET may optionally be followed by a colon
+ (:
) and a syslog log level (e.g, REJECT:info or
+ ACCEPT:debugging). This causes the packet to be logged at the
+ specified level. You may also specify ULOG (must be in upper case) as
+ a log level.This will log to the ULOG target for routing to a separate
+ log through use of ulogd (http://www.gnumonks.org/projects/ulogd).
+
+
+
+ SOURCE - Source hosts to which the rule applies. A
+ comma-separated list of subnets and/or hosts. Hosts may be specified
+ by IP or MAC address; mac addresses must begin with ~
+ and must use -
as a separator.
+
+ Alternatively, clients may be specified by interface name. For
+ example, eth1 specifies a client that communicates with the firewall
+ system through eth1. This may be optionally followed by another colon
+ (:
) and an IP/MAC/subnet address as described above
+ (e.g., eth1:192.168.1.5).
+
+
+
+ DEST - Location of Server. Same as above with the exception that
+ MAC addresses are not allowed.
+
+ Unlike in the SOURCE column, you may specify a range of up to
+ 256 IP addresses using the syntax <first
+ ip>-<last ip>.
+
+
+
+ PROTO - Protocol - Must be tcp
,
+ udp
, icmp
, a number, or
+ all
.
+
+
+
+ DEST PORT(S) - Destination Ports. A comma-separated list of Port
+ names (from /etc/services), port numbers or port
+ ranges; if the protocol is icmp
, this column is
+ interpreted as the destination icmp-type(s).
+
+ A port range is expressed as <low
+ port>:<high port>.
+
+ This column is ignored if PROTOCOL = all but must be entered if
+ any of the following ields are supplied. In that case, it is suggested
+ that this field contain -
.
+
+ If your kernel contains multi-port match support, then only a
+ single Netfilter rule will be generated if in this list and in the
+ CLIENT PORT(S) list below:
+
+
+
+ There are 15 or less ports listed.
+
+
+
+ No port ranges are included.
+
+
+
+ Otherwise, a separate rule will be generated for each
+ port.
+
+
+
+ SOURCE PORT(S) - Port(s) used by the client. If omitted, any
+ source port is acceptable. Specified as a comma-separated list of port
+ names, port numbers or port ranges.
+
+ If you don't want to restrict client ports but need to specify
+ an ADDRESS in the next column, then place "-" in this column.
+
+ If your kernel contains multi-port match support, then only a
+ single Netfilter rule will be generated if in this list and in the
+ DEST PORT(S) list above:
+
+
+
+ There are 15 or less ports listed.
+
+
+
+ No port ranges are included.
+
+
+
+ Otherwise, a separate rule will be generated for each
+ port.
+
+
+
+ RATE LIMIT - You may rate-limit the rule by placing a value in
+ this column:
+
+ <rate>/<interval>[:<burst>]where
+ <rate> is the number of connections per
+ <interval> (sec
or
+ min
) and <burst> is the
+ largest burst permitted. If no <burst> is
+ given, a value of 5 is assumed. There may be no whitespace embedded in
+ the specification.
+
+ Example: 10/sec:20
+
+
+
+ USER/GROUP - For output rules (those with the firewall as their
+ source), you may control connections based on the effective UID and/or
+ GID of the process requesting the connection. This column can contain
+ any of the following:
+
+
+ [!]<user number>[:]
+
+ [!]<user name>[:]
+
+ [!]:<group number>
+
+ [!]:<group name>
+
+ [!]<user
+ number>:<group
+ number>
+
+ [!]<user
+ name>:<group
+ number>
+
+ [!]<user
+ inumber>:<group
+ name>
+
+ [!]<user
+ name>:<group name>
+
+
+
+
+ Omitted column entries should be entered using a dash ("-:).
+
+ Example:
+
+ /etc/shorewall/actions:
+
+ LogAndAccept/etc/shorewall/action.LogAndAccept LOG:info
+ ACCEPT
+
+ To use your action, in /etc/shorewall/rules you
+ might do something like:
+
+ #ACTION SOURCE DEST PROTO DEST PORT(S)
+LogAndAccept loc fw tcp 22
+
+
+
+ Actions and Logging
+
+ Prior to Shorewall 2.1.2, specifying a log level (and optionally a
+ log tag) on a rule that specified a user-defined (or Shorewall-defined)
+ action would log all traffic passed to the action. Beginning with
+ Shorewall 2.1.2, specifying a log level in a rule that specifies a user-
+ or Shorewall-defined action will cause each rule in the action to be
+ logged with the specified level (and tag).
+
+ The extent to which logging of action rules occur is goverend by the
+ following:
+
+
+
+ When you invoke an action and specify a log level, only those
+ rules in the action that have no log level will be changed to log at
+ the level specified at the action invocation.
+
+ Example:
+
+ /etc/shorewall/action.foo
+
+ #TARGET SOURCE DEST PROTO DEST PORT(S)
+ACCEPT - - tcp 22
+bar:info
+
+ /etc/shorewall/rules:
+
+ #ACTION SOURCE DEST PROTO DEST PORT(S)
+foo:debug fw net
+
+ Logging in the invoke 'foo' action will be as if foo had been
+ defined as:
+
+ #TARGET SOURCE DEST PROTO DEST PORT(S)
+ACCEPT:debug - - tcp 22
+bar:info
+
+
+
+ If you follow the log level with "!" then logging will be at
+ that level for all rules recursively invoked by the action.
+
+ Example:
+
+ /etc/shorewall/action.foo
+
+ #TARGET SOURCE DEST PROTO DEST PORT(S)
+ACCEPT - - tcp 22
+bar:info
+
+ /etc/shorewall/rules:
+
+ #ACTION SOURCE DEST PROTO DEST PORT(S)
+foo:debug! fw net
+
+ Logging in the invoke 'foo' action will be as if foo had been
+ defined as:
+
+ #TARGET SOURCE DEST PROTO DEST PORT(S)
+ACCEPT:debug - - tcp 22
+bar:debug
+
+
+
+ The change in Shorewall 2.1.2 has an effect on extension scripts
+ used with user-defined actions. If you define an action 'acton' and you
+ have an /etc/shorewall/acton script then when that
+ script is invoked, the following three variables will be set for use by
+ the script:
+
+
+
+ $CHAIN = the name of the chain where your rules are to be
+ placed. When logging is used on an action invocation, Shorewall
+ creates a chain with a slightly different name from the action
+ itself.
+
+
+
+ $LEVEL = Log level. If empty, no logging was specified.
+
+
+
+ $TAG = Log Tag.
+
+
+
+ Example:
+
+ /etc/shorewall/rules:
+
+ #ACTION SOURCE DEST
+acton:info:test fw net
+
+ Your /etc/shorewall/acton file will be run with:
+
+
+
+ $CHAIN="%acton1"
+
+
+
+ $LEVEL="info"
+
+
+
+ $TAG="test"
+
+
+
+
+
+ Creating an Action using an Extension Script
+
+ There may be cases where you wish to create a chain with rules that
+ can't be constructed using the tools defined in the action.template. In
+ that case, you can use an extension script.
+ If you actually need an action to drop broadcast packets, use
+ the dropBcast standard action rather than create
+ one like this.
+
+
+
+ An action to drop all broadcast packets
+
+ /etc/shorewall/actionsDropBcasts
+
+ /etc/shorewall/action.DropBcasts# This file is empty
+
+ /etc/shorewall/DropBcastsrun_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP
+
+
+
\ No newline at end of file
diff --git a/Shorewall-docs2/Documentation_Index.xml b/Shorewall-docs2/Documentation_Index.xml
index 1b132fc84..494cda17c 100644
--- a/Shorewall-docs2/Documentation_Index.xml
+++ b/Shorewall-docs2/Documentation_Index.xml
@@ -15,15 +15,15 @@
- 2004-12-18
+ 2005-01-19
- 2001-2004
+ 2001-2005
Thomas M. Eastep
- 2.2.0 Beta 4
+ 2.2.0
Permission is granted to copy, distribute and/or modify this
@@ -81,6 +81,10 @@
Accounting
+
+ Actions
+
+
Aliased
(virtual) Interfaces (e.g., eth0:0)
@@ -606,11 +610,6 @@
try if it doesn't work)
-
- User-defined
- Actions
-
-
UID/GID Based Rules
diff --git a/Shorewall-docs2/template.xml b/Shorewall-docs2/template.xml
index 6895743dc..34d1612ea 100644
--- a/Shorewall-docs2/template.xml
+++ b/Shorewall-docs2/template.xml
@@ -15,10 +15,10 @@
- 2004-07-31
+ 2005-07-31
- 2004
+ 2005
Thomas M. Eastep