Date: Wed, 26 Feb 2014 20:32:12 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44077 - head/en_US.ISO8859-1/books/handbook/firewalls Message-ID: <201402262032.s1QKWCZg089826@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402262032.s1QKWCZg089826>