From 26aa63f5e40a1bec3da85092bd368cd474c74822 Mon Sep 17 00:00:00 2001 From: judas_iscariote Date: Mon, 22 Aug 2005 10:07:49 +0000 Subject: [PATCH] very draft docs for macros.. git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@2534 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- Shorewall-docs2/Macros.xml | 515 +++++++++++++++++++++++++++++++++++++ 1 file changed, 515 insertions(+) create mode 100644 Shorewall-docs2/Macros.xml diff --git a/Shorewall-docs2/Macros.xml b/Shorewall-docs2/Macros.xml new file mode 100644 index 000000000..a05e50f51 --- /dev/null +++ b/Shorewall-docs2/Macros.xml @@ -0,0 +1,515 @@ + + +
+ + + + Macros + + + + Tom + + Eastep + + + + Cristian + + Rodríguez + + + + 2005-08-22 + + + 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 Macros? + + Shorewall macros 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. + + Macros can be thought of as templates. When a macro 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 macro causes a log message to be + generated. + + There are three types of Shorewall macros: + + + + Built-in Macros. These macros 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 Macros. 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 + macros.* 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 + macro. + + # +# Shorewall 2.2 /usr/share/shorewall/macro.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 +PARAM - - udp 135,445 +PARAM - - udp 137:139 +PARAM - - udp 1024: 137 +PARAM - - tcp 135,139,445 +#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE + + If you wish to modify one of the standard macros, 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 Macros. 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!!! + +
+ +
+ Defining your own 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 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 fields 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 governed 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" + + + + For an example of how to use these variables, see this article. +
+ +
+ 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 + + + For a richer example, see this + article. +
+
\ No newline at end of file