svn commit: r44077 - head/en_US.ISO8859-1/books/handbook/firewalls
Dru Lavigne
dru at FreeBSD.org
Wed Feb 26 20:32:12 UTC 2014
Author: dru
Date: Wed Feb 26 20:32:11 2014
New Revision: 44077
URL: http://svnweb.freebsd.org/changeset/doc/44077
Log:
Modernize the IPFW Rule Syntax section.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Wed Feb 26 17:05:28 2014 (r44076)
+++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Wed Feb 26 20:32:11 2014 (r44077)
@@ -1757,8 +1757,8 @@ options IPDIVERT # enables NAT</pro
<para>When a packet enters the <application>IPFW</application> firewall,
it is compared against the first rule in the ruleset and
- progresses one rule at a time, moving from top to bottom of
- the set in ascending rule number sequence order. When the
+ progresses one rule at a time, moving from top to bottom in
+ sequence. When the
packet matches the selection parameters of a rule, the rule's
action is executed and the search of the ruleset
terminates for that packet. This is referred to as
@@ -1772,10 +1772,6 @@ options IPDIVERT # enables NAT</pro
to &man.ipfw.8; for details on how these keywords affect rule
processing.</para>
- <para>This section provides an overview of the rule syntax for creating
- stateful rules. For a complete rule syntax
- description, refer to &man.ipfw.8;.</para>
-
<indexterm>
<primary><application>IPFW</application></primary>
@@ -1784,33 +1780,58 @@ options IPDIVERT # enables NAT</pro
<para>When creating an
<application>IPFW</application> rule, keywords must be
- written in the following order. The <literal>#</literal> symbol is used
+ written in the following order. Some keywords are mandatory
+ while other keywords are optional. The words shown in uppercase
+ represent a variable and the words shown in lowercase must
+ precede the variable that follows it. The <literal>#</literal> symbol is used
to mark the start of a comment and may appear at the end of a
rule or on its own line. Blank lines are ignored.</para>
- <para><replaceable>CMD RULE_NUMBER ACTION LOGGING SELECTION
- STATEFUL</replaceable></para>
+ <para><replaceable>CMD RULE_NUMBER set SET_NUMBER ACTION log
+ LOG_AMOUNT PROTO from SRC SRC_PORT to DST DST_PORT
+ OPTIONS</replaceable></para>
+
+ <para>This section provides an overview of these keywords and
+ their options. It is not an exhaustive list of every possible
+ option. Refer to &man.ipfw.8; for a complete description of
+ the rule syntax that can be used when creating
+ <application>IPFW</application> rules.</para>
<variablelist>
<varlistentry>
<term>CMD</term>
<listitem>
- <para>Each new rule has to be prefixed with
- <parameter>add</parameter> to add the rule to the
- internal table.</para>
+ <para>Every rule must start with
+ <parameter>ipfw add</parameter>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RULE_NUMBER</term>
<listitem>
- <para>Each rule is associated with a rule_number in the
+ <para>Each rule is associated with a number in the
range of <literal>1</literal> to
- <literal>65535</literal>.</para>
+ <literal>65534</literal>. The number is used to
+ indicate the order of rule processing. Multiple rules can have the same
+ number, in which case they are checked according to
+ the order in which they have been added.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term>SET_NUMBER</term>
+ <listitem>
+ <para>Each rule is associated with a set number in the
+ range of <literal>0</literal> to
+ <literal>31</literal>. Sets can be individually
+ disabled or enabled, making it possible to quickly add
+ or delete a set of rules. If a SET_NUMBER is not
+ specified, the rule will be added to set <literal>0</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>ACTION</term>
<listitem>
<para>A rule can be associated with one of the following
@@ -1819,15 +1840,10 @@ options IPDIVERT # enables NAT</pro
rule.</para>
<para><parameter>allow | accept | pass |
- permit</parameter></para>
-
- <para>These keywords are equivalent as they allow packets
- that match the rule to exit the firewall rule
- processing. The search terminates at this rule.</para>
-
- <para><parameter>check-state</parameter></para>
+ permit</parameter>: these keywords are equivalent and allow packets
+ that match the rule.</para>
- <para>Checks the packet against the dynamic rules table.
+ <para><parameter>check-state</parameter>: checks the packet against the dynamic state table.
If a match is found, execute the action associated with
the rule which generated this dynamic rule, otherwise
move to the next rule. A <literal>check-state</literal>
@@ -1837,27 +1853,31 @@ options IPDIVERT # enables NAT</pro
<literal>keep-state</literal> or
<literal>limit</literal> rule.</para>
- <para><parameter>deny | drop</parameter></para>
-
- <para>Both words mean the same thing, which is to discard
- packets that match this rule. The search
- terminates.</para>
+ <para><parameter>count</parameter>: updates counters for
+ all packets that match rule. The search continues with
+ the next rule.</para>
+
+ <para><parameter>deny | drop</parameter>: either word discards
+ packets that match this rule.</para>
+
+ <para>Additional actions are available. Refer to
+ &man.ipfw.8; for details.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>LOGGING</term>
+ <term>LOG_AMOUNT</term>
<listitem>
<para>When a packet matches a rule with the
<literal>log</literal> keyword, a message will be logged
to &man.syslogd.8; with a facility name of
<literal>SECURITY</literal>. Logging only occurs if the
number of packets logged for that particular rule does
- not exceed the <literal>logamount</literal> parameter.
- If no <literal>logamount</literal> is specified, the
- limit is taken from the <command>sysctl</command> value
- of <varname>net.inet.ip.fw.verbose_limit</varname>. In
- both cases, a value of zero removes the logging limit.
+ not exceed the optional specified LOG_AMOUNT.
+ If no LOG_AMOUNT is specified, the
+ limit is taken from the value
+ of <varname>net.inet.ip.fw.verbose_limit</varname>. A
+ value of zero removes the logging limit.
Once the limit is reached, logging can be re-enabled by
clearing the logging counter or the packet counter for
that rule, using <command>ipfw reset
@@ -1873,119 +1893,95 @@ options IPDIVERT # enables NAT</pro
</varlistentry>
<varlistentry>
- <term>SELECTION</term>
+ <term>PROTO</term>
<listitem>
- <para>The keywords described in this section are used to
- describe attributes of the packet to be checked when
- determining whether rules match the packet or not. The
- following general-purpose attributes are provided for
- matching, and must be used in this order:</para>
-
- <para><parameter>udp | tcp | icmp</parameter></para>
-
- <para>Any other protocol names found in
- <filename>/etc/protocols</filename> can be used. The
- value specified is the protocol to be matched against.
- This is a mandatory keyword.</para>
-
- <para><parameter>from src to dst</parameter></para>
-
- <para>The <literal>from</literal> and
- <literal>to</literal> keywords are used to match against
- IP addresses. Rules must specify
- <emphasis>both</emphasis> source and destination
- parameters. <literal>any</literal> is a special keyword
- that matches any IP address. <literal>me</literal> is a
- special keyword that matches any IP address configured
- on an interface in the &os; system to represent the PC
- the firewall is running on. Example usage includes
- <literal>from me to any</literal>,
- <literal>from any to me</literal>,
- <literal>from 0.0.0.0/0 to any</literal>,
- <literal>from any to 0.0.0.0/0</literal>,
- <literal>from 0.0.0.0 to any</literal>,
- <literal>from any to 0.0.0.0</literal>, and
- <literal>from me to 0.0.0.0</literal>. IP addresses
- are specified in dotted IP address format followed by
- the mask in CIDR notation, or as a single host in dotted
- IP address format. This keyword is a mandatory
- requirement. The <package>net-mgmt/ipcalc</package>
- port may be used to assist the mask calculation.</para>
-
- <para><parameter>port number</parameter></para>
-
- <para>For protocols which support port numbers, such as
- <acronym>TCP</acronym> and <acronym>UDP</acronym>, it is
- mandatory to include the port number of the service
- that will be matched. Service names from
- <filename>/etc/services</filename> may be used instead
- of numeric port values.</para>
-
- <para><parameter>in | out</parameter></para>
-
- <para>Matches incoming or outgoing packets. It is
- mandatory that one or the other is included as part of
- the rule matching criterion.</para>
-
- <para><parameter>via IF</parameter></para>
-
- <para>Matches packets going through the interface
- specified by device name. The <literal>via</literal>
- keyword causes the interface to always be checked as
- part of the match process.</para>
-
- <para><parameter>setup</parameter></para>
-
- <para>This mandatory keyword identifies the session start
- request for <acronym>TCP</acronym> packets.</para>
-
- <para><parameter>keep-state</parameter></para>
-
- <para>This is a mandatory keyword. Upon a match, the
- firewall will create a dynamic rule, whose default
- behavior is to match bidirectional traffic between
- source and destination IP/port using the same
- protocol.</para>
+ <para>This optional value can be used to specify any
+ protocol name or number found in
+ <filename>/etc/protocols</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SRC</term>
+ <listitem>
+ <para>The <literal>from</literal>
+ keyword must be followed by the source address or a
+ keyword that represents the source address. An address
+ can be represented by the <literal>any</literal>,
+ <literal>me</literal> (any address configured on an
+ interface on this system),
+ <literal>me6</literal>, (any <acronym>IPv6</acronym>
+ address configured on an interface on this system), or
+ <literal>table</literal> followed by the number of a
+ lookup table which contains a list of addresses. When
+ specifying an <acronym>IP</acronym> address, it can be
+ optionally followed by its <acronym>CIDR</acronym> mask
+ or subnet mask. For example, <literal>1.2.3.4/25</literal> or
+ <literal>1.2.3.4:255.255.255.128</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SRC_PORT</term>
+ <listitem>
+ <para>An optional source port can be specified using the
+ port number or name from
+ <filename>/etc/services</filename>.</para>
+ </listitem>
+ </varlistentry>
- <para><parameter>limit {src-addr | src-port | dst-addr |
- dst-port}</parameter></para>
+ <varlistentry>
+ <term>DST</term>
+ <listitem>
+ <para>The <literal>to</literal> keyword must be followed
+ by the destination address or a
+ keyword that represents the destination address. The
+ same keywords and addresses described in the SRC section
+ can be used to describe the destination.</para>
+ </listitem>
+ </varlistentry>
- <para>The firewall will only allow
- <replaceable>N</replaceable> connections with the same
- set of parameters as specified in the rule. One or more
- of source and destination addresses and ports can be
- specified. <literal>limit</literal> and
- <literal>keep-state</literal> can not be used on the
- same rule as they provide the same stateful
- function.</para>
+ <varlistentry>
+ <term>DST_PORT</term>
+ <listitem>
+ <para>An optional destination port can be specified using
+ the port number or name from
+ <filename>/etc/services</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>STATEFUL</term>
+ <term>OPTIONS</term>
<listitem>
- <para>The <literal>check-state</literal> option is used to
- identify where in the <application>IPFW</application>
- ruleset the packet is to be tested against the dynamic
- rules facility. On a match, the packet exits the
- firewall to continue on its way and a new rule is
- dynamically created for the next anticipated packet
- being exchanged during this session. On a no match, the
- packet advances to the next rule in the ruleset for
- testing.</para>
+ <para>Several keywords can follow the source and
+ destination. As the name suggests, OPTIONS are
+ optional. Commonly used options include
+ <literal>in</literal> or
+ <literal>out</literal>, which specify the direction of
+ packet flow, <literal>icmptypes</literal> followed by
+ the type of <acronym>ICMP</acronym> message, and
+ <literal>keep-state</literal>.</para>
+
+ <para>When a <parameter>keep-state</parameter> rule is matched, the
+ firewall will create a dynamic rule which
+ matches bidirectional traffic between the
+ source and destination addresses and ports using the same
+ protocol.</para>
<para>The dynamic rules facility is vulnerable to resource
depletion from a SYN-flood attack which would open a
huge number of dynamic rules. To counter this type of
attack with <application>IPFW</application>, use
- <literal>limit</literal>. This keyword limits the
- number of simultaneous sessions by checking that rule's
- source or destinations fields and using the packet's IP
- address in a search of the open dynamic rules, counting
- the number of times this rule and IP address
+ <literal>limit</literal>. This option limits the
+ number of simultaneous sessions by checking the open dynamic rules, counting
+ the number of times this rule and <acronym>IP</acronym> address
combination occurred. If this count is greater than the
value specified by <literal>limit</literal>, the packet
is discarded.</para>
+
+ <para>Dozens of OPTIONS are available. Refer to
+ &man.ipfw.8; for a description of each available
+ option.</para>
</listitem>
</varlistentry>
</variablelist>
More information about the svn-doc-all
mailing list