From aba63d5c9b6214027eb9e9db0985528ff02578c2 Mon Sep 17 00:00:00 2001 From: Tom Eastep Date: Mon, 13 Dec 2010 09:06:29 -0800 Subject: [PATCH] More action/macro documentation Signed-off-by: Tom Eastep --- Shorewall/Macros/macro.template | 411 +------------------------------- Shorewall/action.template | 187 +-------------- Shorewall/configfiles/rules | 4 +- docs/Actions.xml | 11 +- docs/Macros.xml | 10 +- 5 files changed, 31 insertions(+), 592 deletions(-) diff --git a/Shorewall/Macros/macro.template b/Shorewall/Macros/macro.template index 1f7740fdc..717cf5b5f 100644 --- a/Shorewall/Macros/macro.template +++ b/Shorewall/Macros/macro.template @@ -15,410 +15,7 @@ # - All entries in a macro undergo substitution when the macro is # invoked in the rules file. # -# - Macros used in action bodies may not invoke other macros. -# -# The columns in the file are the same as those in the action.template file but -# have different restrictions: -# -# Columns are: -# -# ACTION ACCEPT, DROP, REJECT, DNAT, DNAT-, REDIRECT, CONTINUE, -# LOG, QUEUE, PARAM or an name. -# -# ACCEPT -- allow the connection request -# ACCEPT+ -- like ACCEPT but also excludes the -# connection from any subsequent -# DNAT[-] or REDIRECT[-] rules -# NONAT -- Excludes the connection from any -# subsequent DNAT[-] or REDIRECT[-] -# rules but doesn't generate a rule -# to accept the traffic. -# DROP -- ignore the request -# REJECT -- disallow the request and return an -# icmp-unreachable or an RST packet. -# DNAT -- Forward the request to another -# system (and optionally another -# port). -# DNAT- -- Advanced users only. -# Like DNAT but only generates the -# DNAT iptables rule and not -# the companion ACCEPT rule. -# SAME -- Similar to DNAT except that the -# port may not be remapped and when -# multiple server addresses are -# listed, all requests from a given -# remote system go to the same -# server. -# SAME- -- Advanced users only. -# Like SAME but only generates the -# NAT iptables rule and not -# the companion ACCEPT rule. -# REDIRECT -- Redirect the request to a local -# port on the firewall. -# REDIRECT- -# -- Advanced users only. -# Like REDIRET but only generates the -# REDIRECT iptables rule and not -# the companion ACCEPT rule. -# -# CONTINUE -- (For experts only). Do not process -# any of the following rules for this -# (source zone,destination zone). If -# The source and/or destination IP -# address falls into a zone defined -# later in /etc/shorewall/zones, this -# connection request will be passed -# to the rules defined for that -# (those) zone(s). -# LOG -- Simply log the packet and continue. -# QUEUE -- Queue the packet to a user-space -# application such as ftwall -# (http://p2pwall.sf.net). -# PARAM -- If you code PARAM as the action in -# a macro then when you invoke the -# macro, you can include the name of -# the macro followed by a slash ("/") -# and an ACTION (either builtin or -# user-defined. All instances of -# PARAM in the body of the macro will -# be replaced with the ACTION. -# -- The name of an action defined in -# /usr/share/shorewall/actions.std or -# in /etc/shorewall/actions. -# -# The ACTION may optionally be followed -# by ":" and a syslog log level (e.g, REJECT:info or -# DNAT:debug). 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). -# -# Actions specifying logging may be followed by a -# log tag (a string of alphanumeric characters) -# are appended to the string generated by the -# LOGPREFIX (in /etc/shorewall/shorewall.conf). -# -# Example: ACCEPT:info:ftp would include 'ftp ' -# at the end of the log prefix generated by the -# LOGPREFIX setting. -# -# SOURCE Source hosts to which the rule applies. May be a zone -# defined in /etc/shorewall/zones, $FW to indicate the -# firewall itself, "all", "all+" or "none" If the ACTION -# is DNAT or REDIRECT, sub-zones of the specified zone -# may be excluded from the rule by following the zone -# name with "!' and a comma-separated list of sub-zone -# names. -# -# When "none" is used either in the SOURCE or DEST -# column, the rule is ignored. -# -# When "all" is used either in the SOURCE or DEST column -# intra-zone traffic is not affected. When "all+" is -# used, intra-zone traffic is affected. -# -# Except when "all[+]" is specified, clients may be -# further restricted to a list of subnets and/or hosts by -# appending ":" and 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. -# -# Hosts may be specified as an IP address range using the -# syntax -. This requires that -# your kernel and iptables contain iprange match support. -# If you kernel and iptables have ipset match support -# then you may give the name of an ipset prefaced by "+". -# The ipset name may be optionally followed by a number -# from 1 to 6 enclosed in square brackets ([]) to -# indicate the number of levels of source bindings to be -# matched. -# -# dmz:192.168.2.2 Host 192.168.2.2 in the DMZ -# -# net:155.186.235.0/24 Subnet 155.186.235.0/24 on the -# Internet -# -# loc:192.168.1.1,192.168.1.2 -# Hosts 192.168.1.1 and -# 192.168.1.2 in the local zone. -# loc:~00-A0-C9-15-39-78 Host in the local zone with -# MAC address 00:A0:C9:15:39:78. -# -# net:192.0.2.11-192.0.2.17 -# Hosts 192.0.2.11-192.0.2.17 in -# the net zone. -# -# Alternatively, clients may be specified by interface -# by appending ":" to the zone name followed by the -# interface name. For example, loc: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., loc:eth1:192.168.1.5). -# -# DEST Location of Server. May be a zone defined in -# /etc/shorewall/zones, $FW to indicate the firewall -# itself, "all". "all+" or "none". -# -# When "none" is used either in the SOURCE or DEST -# column, the rule is ignored. -# -# When "all" is used either in the SOURCE or DEST column -# intra-zone traffic is not affected. When "all+" is -# used, intra-zone traffic is affected. -# -# Except when "all[+]" is specified, the server may be -# further restricted to a particular subnet, host or -# interface by appending ":" and the subnet, host or -# interface. See above. -# -# Restrictions: -# -# 1. MAC addresses are not allowed. -# 2. In DNAT rules, only IP addresses are -# allowed; no FQDNs or subnet addresses -# are permitted. -# 3. You may not specify both an interface and -# an address. -# -# Like in the SOURCE column, you may specify a range of -# up to 256 IP addresses using the syntax -# -. When the ACTION is DNAT or DNAT-, -# the connections will be assigned to addresses in the -# range in a round-robin fashion. -# -# If you kernel and iptables have ipset match support -# then you may give the name of an ipset prefaced by "+". -# The ipset name may be optionally followed by a number -# from 1 to 6 enclosed in square brackets ([]) to -# indicate the number of levels of destination bindings -# to be matched. Only one of the SOURCE and DEST columns -# may specify an ipset name. -# -# The port that the server is listening on may be -# included and separated from the server's IP address by -# ":". If omitted, the firewall will not modifiy the -# destination port. A destination port may only be -# included if the ACTION is DNAT or REDIRECT. -# -# Example: loc:192.168.1.3:3128 specifies a local -# server at IP address 192.168.1.3 and listening on port -# 3128. The port number MUST be specified as an integer -# and not as a name from /etc/services. -# -# if the ACTION is REDIRECT, this column needs only to -# contain the port number on the firewall that the -# request should be redirected to. -# -# PROTO Protocol - Must be "tcp", "tcp:syn", "udp", "icmp", -# "ipp2p", "ipp2p:udp", "ipp2p:all" a number, or "all". -# "ipp2p*" requires ipp2p match support in your kernel -# and iptables. -# -# "tcp:syn" implies "tcp" plus the SYN flag must be -# set and the RST,ACK and FIN flags must be reset. -# -# 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). -# -# If the protocol is ipp2p*, this column is interpreted -# as an ipp2p option without the leading "--" (example -# "bit" for bit-torrent). If no port is given, "ipp2p" is -# assumed. -# -# A port range is expressed as :. -# -# 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 the CLIENT PORT(S) list below: -# 1. There are 15 or less ports listed. -# 2. No port ranges are included. -# Otherwise, a separate rule will be generated for each -# port. -# -# SOURCE PORT(S) (Optional) 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 ORIGINAL DEST 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 the DEST PORT(S) list above: -# 1. There are 15 or less ports listed. -# 2. No port ranges are included. -# Otherwise, a separate rule will be generated for each -# port. -# -# ORIGINAL Original destination IP address. Must be omitted ( -# DEST or '-') if the macro is to be used from within -# an action. See 'man shorewall-rules'. -# -# RATE LIMIT You may rate-limit the rule by placing a value in -# this column: -# -# /[:] -# -# where is the number of connections per -# ("sec" or "min") and is the -# largest burst permitted. If no is given, -# a value of 5 is assumed. There may be no -# no whitespace embedded in the specification. -# -# Example: 10/sec:20 -# -# USER/GROUP This column may only be non-empty if the SOURCE is -# the firewall itself. -# -# The column may contain: -# -# [!][][:][+] -# -# When this column is non-empty, the rule applies only -# if the program generating the output is running under -# the effective and/or specified (or is -# NOT running under that id if "!" is given). -# -# Examples: -# -# joe #program must be run by joe -# :kids #program must be run by a member of -# #the 'kids' group -# !:kids #program must not be run by a member -# #of the 'kids' group -# +upnpd #program named upnpd (This feature was -# #removed from Netfilter in kernel -# #version 2.6.14). -# -# MARK Specifies a MARK value to match. Must be empty or -# '-' if the macro is to be used within an action. -# -# [!]value[/mask][:C] -# -# Defines a test on the existing packet or connection -# mark. The rule will match only if the test returns -# true. -# -# If you don't want to define a test but need to -# specify anything in the following columns, -# place a "-" in this field. -# -# ! -# -# Inverts the test (not equal) -# -# value -# -# Value of the packet or connection mark. -# -# mask -# -# A mask to be applied to the mark before -# testing. -# -# :C -# -# Designates a connection mark. If omitted, the -# packet mark's value is tested. -# -# CONNLIMIT Must be empty or '-' if the macro is to be used within -# an action. -# -# [!]limit[:mask] -# -# May be used to limit the number of simultaneous -# connections from each individual host to limit -# connections. Requires connlimit match in your kernel -# and iptables. While the limit is only checked on rules -# specifying CONNLIMIT, the number of current connections -# is calculated over all current connections from the -# SOURCE host. By default, the limit is applied to each -# host but can be made to apply to networks of hosts by -# specifying a mask. The mask specifies the width of a -# VLSM mask to be applied to the source address; the -# number of current connections is then taken over all -# hosts in the subnet source-address/mask. When ! is -# specified, the rule matches when the number of -# connection exceeds the limit. -# -# TIME Must be empty or '-' if the macro is to be used within -# an action. -# -# -# [&...] -# -# timeelement may be: -# -# timestart=hh:mm[:ss] -# -# Defines the starting time of day. -# -# timestop=hh:mm[:ss] -# -# Defines the ending time of day. -# -# utc -# -# Times are expressed in Greenwich Mean -# Time. -# -# localtz -# -# Times are expressed in Local Civil Time -# (default). -# -# weekdays=ddd[,ddd]... -# -# where ddd is one of Mon, Tue, Wed, Thu, -# Fri, Sat or Sun -# -# monthdays=dd[,dd],... -# -# where dd is an ordinal day of the month# -# -# datestart=yyyy[-mm[-dd[Thh[:mm[:ss]]]]] -# -# Defines the starting date and time. -# -# datestop=yyyy[-mm[-dd[Thh[:mm[:ss]]]]] -# -# Defines the ending date and time. -# -# HEADERS [any:|exactly:]
-# -# where
is a comma-separated list of headers from the following: -# -# -# Long Name Short Name Number -# -------------------------------------- -# auth ah 50 -# esp esp 51 -# hop-by-hop hop 0 -# route ipv6-route 41 -# frag ipv6-frag 44 -# none ipv6-nonxt 59 -# protocol proto 255 -# -# If 'any:' is specified, the rule will match if any of the listed -# headers are present. If 'exactly:' is specified, the will match -# packets that exactly include all specified headers. If neither is -# given, 'any:' is assumed. -# -# +# Columns are the same as in /etc/shorewall/rules. # A few examples should help show how Macros work. # # /etc/shorewall/macro.FwdFTP: @@ -477,6 +74,6 @@ ####################################################################################################### # DO NOT REMOVE THE FOLLOWING LINE FORMAT 2 -####################################################################################################### -#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ ORIGINAL -# PORT(S) PORT(S) DEST LIMIT GROUP DEST +#################################################################################################################################################################### +#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ MARK CONNLIMIT TIME HEADERS +# PORT PORT(S) DEST LIMIT GROUP diff --git a/Shorewall/action.template b/Shorewall/action.template index 205d48b99..f4ee397e1 100644 --- a/Shorewall/action.template +++ b/Shorewall/action.template @@ -16,184 +16,11 @@ # Please see http://shorewall.net/Actions.html for additional # information. # -# Columns are: +# Columns are the same as in /etc/shorewall/rules. # -# -# TARGET ACCEPT, DROP, REJECT, LOG, QUEUE, CONTINUE, a -# or a previously-defined -# -# ACCEPT -- allow the connection request -# DROP -- ignore the request -# REJECT -- disallow the request and return an -# icmp-unreachable or an RST packet. -# LOG -- Simply log the packet and continue. -# QUEUE -- Queue the packet to a user-space -# application such as p2pwall. -# CONTINUE -- Stop processing this action and -# return to the point where the -# action was invoked. -# -- An defined in -# /etc/shorewall/actions. -# The must appear in that -# file BEFORE the one being defined -# in this file. -# -- The name of a macro defined in a -# file named macro.. If -# the macro accepts an action -# parameter (Look at the macro -# source to see if it has PARAM in -# the TARGET column) then the macro -# name is followed by "/" and the -# action (ACCEPT, DROP, REJECT, ...) -# to be substituted for the -# parameter. Example: FTP/ACCEPT. -# -# The TARGET may optionally be followed -# by ":" and a syslog log level (e.g, REJECT:info or -# ACCEPT:debugging). This causes the packet to be -# logged at the specified level. -# -# The special log level 'none' does not result in logging -# but rather exempts the rule from being overridden by a -# non-forcing log level when the action is invoked. -# -# 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). -# -# Actions specifying logging may be followed by a -# log tag (a string of alphanumeric characters) -# are appended to the string generated by the -# LOGPREFIX (in /etc/shorewall/shorewall.conf). -# -# Example: ACCEPT:info:ftp would include 'ftp ' -# at the end of the log prefix generated by the -# LOGPREFIX setting. -# -# 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. -# -# 192.168.2.2 Host 192.168.2.2 -# -# 155.186.235.0/24 Subnet 155.186.235.0/24 -# -# 10.0.0.4-10.0.0.9 Range of IP addresses; your -# kernel and iptables must have -# iprange match support. -# -# +remote The name of an ipset prefaced -# by "+". Your kernel and -# iptables must have set match -# support -# -# +remote[4] The name of the ipset may -# followed by a number of -# levels of ipset bindings -# enclosed in square brackets. -# -# 192.168.1.1,192.168.1.2 -# Hosts 192.168.1.1 and -# 192.168.1.2. -# ~00-A0-C9-15-39-78 Host with -# MAC address 00:A0:C9:15:39:78. -# -# 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 destination host. Same as above with -# the exception that MAC addresses are not allowed and -# that you cannot specify an ipset name in both the -# SOURCE and DEST columns. -# -# PROTO Protocol - Must be "tcp", "tcp:syn", "udp", "icmp", -# "ipp2p", "ipp2p:udp", "ipp2p:all", a number, or "all". -# "ipp2p*" requires ipp2p match support in your kernel -# and iptables. -# -# "tcp:syn" implies "tcp" plus the SYN flag must be -# set and the RST, ACK and FIN flags must be reset. -# -# 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 :. -# -# 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 the CLIENT PORT(S) list below: -# 1. There are 15 or less ports listed. -# 2. No port ranges are included. -# Otherwise, a separate rule will be generated for each -# port. -# -# SOURCE PORT(S) (Optional) 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 the DEST PORT(S) list above: -# 1. There are 15 or less ports listed. -# 2. 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: -# -# /[:] -# -# where is the number of connections per -# ("sec" or "min") and is the -# largest burst permitted. If no is given, -# a value of 5 is assumed. There may be no -# no whitespace embedded in the specification. -# -# Example: 10/sec:20 -# -# USER/GROUP This column may only be non-empty if the SOURCE is -# the firewall itself. -# -# The column may contain: -# -# [!][][:][+] -# -# When this column is non-empty, the rule applies only -# if the program generating the output is running under -# the effective and/or specified (or is -# NOT running under that id if "!" is given). -# -# Examples: -# -# joe #program must be run by joe -# :kids #program must be run by a member of -# #the 'kids' group -# !:kids #program must not be run by a member -# #of the 'kids' group -# +upnpd #program named upnpd (This feature was -# #removed from Netfilter in kernel -# #version 2.6.14). -# -############################################################################### -#TARGET SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ -# PORT PORT(S) DEST LIMIT GROUP +####################################################################################################### +# DO NOT REMOVE THE FOLLOWING LINE +FORMAT 2 +#################################################################################################################################################################### +#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ MARK CONNLIMIT TIME HEADERS +# PORT PORT(S) DEST LIMIT GROUP diff --git a/Shorewall/configfiles/rules b/Shorewall/configfiles/rules index 502a38bca..2da088fc7 100644 --- a/Shorewall/configfiles/rules +++ b/Shorewall/configfiles/rules @@ -6,8 +6,8 @@ # The manpage is also online at # http://www.shorewall.net/manpages/shorewall-rules.html # -#################################################################################################################################################### -#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ MARK CONNLIMIT TIME +#################################################################################################################################################################### +#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ MARK CONNLIMIT TIME HEADERS # PORT PORT(S) DEST LIMIT GROUP #SECTION ESTABLISHED #SECTION RELATED diff --git a/docs/Actions.xml b/docs/Actions.xml index 47de780ef..26064f2ba 100644 --- a/docs/Actions.xml +++ b/docs/Actions.xml @@ -213,8 +213,15 @@ ACCEPT - - tcp 135,139,445 - Columns in the action.template file are as - follows: + Beginning with Shorewall 4.4.16, the columns + in action.template are the same as those in shorewall-rules (5). + The first non-commentary line in the template must be + + FORMAT 2 + + Prior to 4.4.16, columns in the action.template + file were as follows: diff --git a/docs/Macros.xml b/docs/Macros.xml index a5d47f25a..0b8890c15 100644 --- a/docs/Macros.xml +++ b/docs/Macros.xml @@ -277,7 +277,15 @@ ACCEPT fw loc tcp 135,139,445 - Columns in the macro.template file are as follows: + Beginning with Shorewall 4.4.16, the columns + in macro.template are the same as those in shorewall-rules (5). + The first non-commentary line in the template must be + + FORMAT 2 + + Before 4.4.16, columns in the macro.template file were as + follows: