From owner-svn-doc-all@FreeBSD.ORG Wed Feb 26 20:32:12 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 50046BE1; Wed, 26 Feb 2014 20:32:12 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 37CCD18CE; Wed, 26 Feb 2014 20:32:12 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1QKWCDk089827; Wed, 26 Feb 2014 20:32:12 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1QKWCZg089826; Wed, 26 Feb 2014 20:32:12 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402262032.s1QKWCZg089826@svn.freebsd.org> From: Dru Lavigne Date: Wed, 26 Feb 2014 20:32:12 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 26 Feb 2014 20:32:12 -0000 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 NATWhen a packet enters the IPFW 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 - This section provides an overview of the rule syntax for creating - stateful rules. For a complete rule syntax - description, refer to &man.ipfw.8;. - IPFW @@ -1784,33 +1780,58 @@ options IPDIVERT # enables NATWhen creating an IPFW rule, keywords must be - written in the following order. The # 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 # 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. - CMD RULE_NUMBER ACTION LOGGING SELECTION - STATEFUL + CMD RULE_NUMBER set SET_NUMBER ACTION log + LOG_AMOUNT PROTO from SRC SRC_PORT to DST DST_PORT + OPTIONS + + 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 + IPFW rules. CMD - Each new rule has to be prefixed with - add to add the rule to the - internal table. + Every rule must start with + ipfw add. RULE_NUMBER - Each rule is associated with a rule_number in the + Each rule is associated with a number in the range of 1 to - 65535. + 65534. 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. + SET_NUMBER + + Each rule is associated with a set number in the + range of 0 to + 31. 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 0. + + + + + ACTION A rule can be associated with one of the following @@ -1819,15 +1840,10 @@ options IPDIVERT # enables NAT allow | accept | pass | - permit - - These keywords are equivalent as they allow packets - that match the rule to exit the firewall rule - processing. The search terminates at this rule. - - check-state + permit: these keywords are equivalent and allow packets + that match the rule. - Checks the packet against the dynamic rules table. + check-state: 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 check-state @@ -1837,27 +1853,31 @@ options IPDIVERT # enables NATkeep-state or limit rule. - deny | drop - - Both words mean the same thing, which is to discard - packets that match this rule. The search - terminates. + count: updates counters for + all packets that match rule. The search continues with + the next rule. + + deny | drop: either word discards + packets that match this rule. + + Additional actions are available. Refer to + &man.ipfw.8; for details. - LOGGING + LOG_AMOUNT When a packet matches a rule with the log keyword, a message will be logged to &man.syslogd.8; with a facility name of SECURITY. Logging only occurs if the number of packets logged for that particular rule does - not exceed the logamount parameter. - If no logamount is specified, the - limit is taken from the sysctl value - of net.inet.ip.fw.verbose_limit. 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 net.inet.ip.fw.verbose_limit. 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 ipfw reset @@ -1873,119 +1893,95 @@ options IPDIVERT # enables NAT - SELECTION + PROTO - 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: - - udp | tcp | icmp - - Any other protocol names found in - /etc/protocols can be used. The - value specified is the protocol to be matched against. - This is a mandatory keyword. - - from src to dst - - The from and - to keywords are used to match against - IP addresses. Rules must specify - both source and destination - parameters. any is a special keyword - that matches any IP address. me 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 - from me to any, - from any to me, - from 0.0.0.0/0 to any, - from any to 0.0.0.0/0, - from 0.0.0.0 to any, - from any to 0.0.0.0, and - from me to 0.0.0.0. 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 net-mgmt/ipcalc - port may be used to assist the mask calculation. - - port number - - For protocols which support port numbers, such as - TCP and UDP, it is - mandatory to include the port number of the service - that will be matched. Service names from - /etc/services may be used instead - of numeric port values. - - in | out - - Matches incoming or outgoing packets. It is - mandatory that one or the other is included as part of - the rule matching criterion. - - via IF - - Matches packets going through the interface - specified by device name. The via - keyword causes the interface to always be checked as - part of the match process. - - setup - - This mandatory keyword identifies the session start - request for TCP packets. - - keep-state - - 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. + This optional value can be used to specify any + protocol name or number found in + /etc/protocols. + + + + + SRC + + The from + keyword must be followed by the source address or a + keyword that represents the source address. An address + can be represented by the any, + me (any address configured on an + interface on this system), + me6, (any IPv6 + address configured on an interface on this system), or + table followed by the number of a + lookup table which contains a list of addresses. When + specifying an IP address, it can be + optionally followed by its CIDR mask + or subnet mask. For example, 1.2.3.4/25 or + 1.2.3.4:255.255.255.128. + + + + + SRC_PORT + + An optional source port can be specified using the + port number or name from + /etc/services. + + - limit {src-addr | src-port | dst-addr | - dst-port} + + DST + + The to 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. + + - The firewall will only allow - N 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. limit and - keep-state can not be used on the - same rule as they provide the same stateful - function. + + DST_PORT + + An optional destination port can be specified using + the port number or name from + /etc/services. - STATEFUL + OPTIONS - The check-state option is used to - identify where in the IPFW - 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. + Several keywords can follow the source and + destination. As the name suggests, OPTIONS are + optional. Commonly used options include + in or + out, which specify the direction of + packet flow, icmptypes followed by + the type of ICMP message, and + keep-state. + + When a keep-state 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. 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 IPFW, use - limit. 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 + limit. This option limits the + number of simultaneous sessions by checking the open dynamic rules, counting + the number of times this rule and IP address combination occurred. If this count is greater than the value specified by limit, the packet is discarded. + + Dozens of OPTIONS are available. Refer to + &man.ipfw.8; for a description of each available + option.