From owner-svn-doc-all@FreeBSD.ORG Tue Feb 25 19:40:14 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 5DC2C277; Tue, 25 Feb 2014 19:40:14 +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 47A0310FE; Tue, 25 Feb 2014 19:40:14 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1PJeE8w078961; Tue, 25 Feb 2014 19:40:14 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1PJeE0u078960; Tue, 25 Feb 2014 19:40:14 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402251940.s1PJeE0u078960@svn.freebsd.org> From: Dru Lavigne Date: Tue, 25 Feb 2014 19:40:14 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44057 - 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: Tue, 25 Feb 2014 19:40:14 -0000 Author: dru Date: Tue Feb 25 19:40:13 2014 New Revision: 44057 URL: http://svnweb.freebsd.org/changeset/doc/44057 Log: White space fix only. Translators can ignore. 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 Tue Feb 25 19:00:35 2014 (r44056) +++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Tue Feb 25 19:40:13 2014 (r44057) @@ -78,12 +78,11 @@ &os; has three firewalls built into the base system: - PF, - IPFW, and IPFILTER, also known as - IPF. - &os; also provides two traffic shapers for controlling bandwidth - usage: &man.altq.4; and &man.dummynet.4;. - ALTQ has + PF, IPFW, + and IPFILTER, also known as + IPF. &os; also provides two traffic + shapers for controlling bandwidth usage: &man.altq.4; and + &man.dummynet.4;. ALTQ has traditionally been closely tied with PF and dummynet with @@ -1593,23 +1592,23 @@ block drop out quick on $ext_if from any IPFW - IPFW is a stateful firewall written for - &os; which supports both IPv4 - and IPv6. It is comprised of several components: the kernel firewall - filter rule processor and its integrated packet accounting - facility, the logging facility, - NAT, the &man.dummynet.4; traffic shaper, - a forward facility, a bridge - facility, and an ipstealth facility. + IPFW is a stateful firewall + written for &os; which supports both IPv4 and + IPv6. It is comprised of several components: + the kernel firewall filter rule processor and its integrated + packet accounting facility, the logging facility, + NAT, the &man.dummynet.4; traffic shaper, a + forward facility, a bridge facility, and an ipstealth + facility. &os; provides a sample ruleset in - /etc/rc.firewall which - defines several firewall types for common scenarios to assist - novice users in generating an appropriate ruleset. - IPFW provides a powerful syntax which advanced users can - use to craft customized rulesets that meet the security - requirements of a given environment. - + /etc/rc.firewall which defines several + firewall types for common scenarios to assist novice users in + generating an appropriate ruleset. + IPFW provides a powerful syntax which + advanced users can use to craft customized rulesets that meet + the security requirements of a given environment. + This section describes how to enable IPFW, provides an overview of its rule syntax, and demonstrates several rulesets for common @@ -1624,8 +1623,10 @@ block drop out quick on $ext_if from any enabling - IPFW is included in the basic &os; install as a kernel - loadable module, meaning that a custom kernel is not needed in order to enable IPFW. + IPFW is included in the basic + &os; install as a kernel loadable module, meaning that a + custom kernel is not needed in order to enable + IPFW. kernel options @@ -1669,8 +1670,8 @@ options IPDIVERT # enables NATfirewall_enable="YES" - To use one of the default firewall types provided by - &os;, add another line which specifies the type: + To use one of the default firewall types provided by &os;, + add another line which specifies the type: firewall_type="open" @@ -1701,19 +1702,18 @@ options IPDIVERT # enables NAT - filename: - full path of the file containing the firewall - rules. + filename: full path of the file + containing the firewall rules. - To instead load a custom ruleset, either - set the filename value of + To instead load a custom ruleset, either set the + filename value of firewall_type or set the firewall_script variable to the absolute path of an executable script that includes - IPFW commands. This example script - blocks all incoming and outgoing traffic: + IPFW commands. This example script blocks + all incoming and outgoing traffic: #!/bin/sh @@ -1750,10 +1750,9 @@ ipfw add deny out If the machine is acting as a gateway providing - NAT using &man.natd.8;, - refer to for information - regarding the required /etc/rc.conf - options. + NAT using &man.natd.8;, refer to for information regarding the + required /etc/rc.conf options. @@ -1771,12 +1770,12 @@ ipfw add deny out changes. ipfw is a useful way to display the - running firewall rules to the console screen. The IPFW - accounting facility dynamically creates a counter for each - rule that counts each packet that matches the rule. During - the process of testing a rule, listing the rule with its - counter is one way to determine if the rule is - functioning as expected. + running firewall rules to the console screen. The + IPFW accounting facility + dynamically creates a counter for each rule that counts each + packet that matches the rule. During the process of testing a + rule, listing the rule with its counter is one way to + determine if the rule is functioning as expected. To list all the running rules in sequence: @@ -1830,13 +1829,14 @@ ipfw add deny out action field value is executed and the search of the ruleset terminates for that packet. This is referred to as first match wins. If the packet does not match - any of the rules, it gets caught by the mandatory IPFW default - rule, number 65535, which denies all packets and silently - discards them. However, if the packet matches a rule that - contains the count, - skipto, or tee keywords, - the search continues. Refer to &man.ipfw.8; for details on - how these keywords affect rule processing. + any of the rules, it gets caught by the mandatory + IPFW default rule, number 65535, + which denies all packets and silently discards them. However, + if the packet matches a rule that contains the + count, skipto, or + tee keywords, the search continues. Refer + to &man.ipfw.8; for details on how these keywords affect rule + processing. The examples in this section create an inclusive type firewall ruleset containing the stateful keep @@ -1845,212 +1845,219 @@ ipfw add deny out via options. For a complete rule syntax description, refer to &man.ipfw.8;. - - IPFW + + IPFW - rule syntax - + rule syntax + - This section describes the keywords which comprise an - IPFW rule. Keywords must be written in - the following order. # is used to mark - the start of a comment and may appear at the end of a rule - line or on its own line. Blank lines are ignored. + This section describes the keywords which comprise an + IPFW rule. Keywords must be + written in the following order. # is used + to mark the start of a comment and may appear at the end of a + rule line or on its own line. Blank lines are ignored. - CMD RULE_NUMBER ACTION LOGGING SELECTION - STATEFUL + CMD RULE_NUMBER ACTION LOGGING SELECTION + STATEFUL - - + + CMD - Each new rule has to be prefixed with - add to add the rule to the internal - table. - - + Each new rule has to be prefixed with + add to add the rule to the + internal table. + + RULE_NUMBER - Each rule is associated with a rule_number in the - range of 1 to - 65535. - - + Each rule is associated with a rule_number in the + range of 1 to + 65535. + + ACTION - A rule can be associated with one of the following - actions. The specified action will be executed when the - packet matches the selection criterion of the rule. - - 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 - - Checks the packet against the dynamic rules 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 - rule does not have selection criterion. If no - check-state rule is present in the - ruleset, the dynamic rules table is checked at the first - keep-state or limit - rule. - - deny | drop - - Both words mean the same thing, which is to discard - packets that match this rule. The search - terminates. - - + A rule can be associated with one of the following + actions. The specified action will be executed when the + packet matches the selection criterion of the + rule. + + 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 + + Checks the packet against the dynamic rules 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 + rule does not have selection criterion. If no + check-state rule is present in the + ruleset, the dynamic rules table is checked at the first + keep-state or + limit rule. + + deny | drop + + Both words mean the same thing, which is to discard + packets that match this rule. The search + terminates. + + Logging - 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. 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 log. - - - Logging is done after all other packet matching - conditions have been met, and before performing the - final action on the packet. The administrator decides - which rules to enable logging on. - - - + 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. + 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 + log. + + + Logging is done after all other packet matching + conditions have been met, and before performing the + final action on the packet. The administrator decides + which rules to enable logging on. + + + Selection - 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. - - limit {src-addr | src-port | dst-addr | - dst-port} - - 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. - - + 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. + + limit {src-addr | src-port | dst-addr | + dst-port} + + 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. + + - - Stateful Rule Option - - 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. - - 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 - combination occurred. If this count is greater than the - value specified by limit, the packet is - discarded. - - - + + Stateful Rule Option + + 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. + + 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 + combination occurred. If this count is greater than the + value specified by limit, the packet + is discarded. + + + Logging Firewall Messages @@ -2061,16 +2068,17 @@ ipfw add deny out logging - Even with the logging facility enabled, IPFW will not - generate any rule logging on its own. The firewall - administrator decides which rules in the ruleset will be - logged, and adds the log keyword to those - rules. Normally only deny rules are logged. It is - customary to duplicate the ipfw default deny - everything rule with the log - keyword included as the last rule in the ruleset. This - way, it is possible to see all the packets that did not - match any of the rules in the ruleset. + Even with the logging facility enabled, + IPFW will not generate any rule + logging on its own. The firewall administrator decides + which rules in the ruleset will be logged, and adds the + log keyword to those rules. Normally + only deny rules are logged. It is customary to duplicate + the ipfw default deny everything rule with + the log keyword included as the last rule + in the ruleset. This way, it is possible to see all the + packets that did not match any of the rules in the + ruleset. Logging is a two edged sword. If one is not careful, an over abundance of log data or a DoS attack can fill the @@ -2102,15 +2110,15 @@ ipfw add deny out Building a Rule Script - Most experienced IPFW users create a file containing - the rules and code them in a manner compatible with running - them as a script. The major benefit of doing this is the - firewall rules can be refreshed in mass without the need - of rebooting the system to activate them. This method is - convenient in testing new rules as the procedure can - be executed as many times as needed. Being a script, - symbolic substitution can be used for frequently used - values to be substituted into multiple rules. + Most experienced IPFW users + create a file containing the rules and code them in a manner + compatible with running them as a script. The major benefit + of doing this is the firewall rules can be refreshed in mass + without the need of rebooting the system to activate them. + This method is convenient in testing new rules as the + procedure can be executed as many times as needed. Being a + script, symbolic substitution can be used for frequently + used values to be substituted into multiple rules. This example script is compatible with the syntax used by the &man.sh.1;, &man.csh.1;, and &man.tcsh.1; shells. @@ -2367,12 +2375,13 @@ pif="dc0" # public interface name of There are some additional configuration statements that need to be enabled to activate the NAT - function of IPFW. For a customized kernel, the kernel - configuration file needs + function of IPFW. For a + customized kernel, the kernel configuration file needs option IPDIVERT added to the other IPFIREWALL options. - In addition to the normal IPFW options in + In addition to the normal + IPFW options in /etc/rc.conf, the following are needed: @@ -2380,10 +2389,9 @@ pif="dc0" # public interface name of natd_interface="rl0" # interface name of public Internet NIC natd_flags="-dynamic -m" # -m = preserve port numbers if possible - Utilizing stateful rules with a - divert natd rule complicates the ruleset - logic. The positioning of the - check-state, and + Utilizing stateful rules with a divert + natd rule complicates the ruleset logic. The + positioning of the check-state, and divert natd rules in the ruleset is critical and a new action type is used, called skipto. When using @@ -3442,8 +3450,9 @@ map dc0 10.0.10.0/29 -> 0/32NAT if they match the third rule. Without the FTP proxy, the following - firewall rules would instead be needed. Note that without the proxy, - all ports above 1024 need to be allowed: + firewall rules would instead be needed. Note that without the + proxy, all ports above 1024 need to be + allowed: # Allow out LAN PC client FTP to public Internet # Active and passive modes @@ -3455,13 +3464,13 @@ pass out quick on rl0 proto tcp from any # Active mode let data channel in from FTP server pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state - Whenever the file containing the NAT rules - is edited, run - ipnat with to delete - the current NAT rules and flush the - contents of the dynamic translation table. Include - and specify the name - of the NAT ruleset to load: + Whenever the file containing the NAT + rules is edited, run ipnat with + to delete the current + NAT rules and flush the contents of the + dynamic translation table. Include and + specify the name of the NAT ruleset to + load: &prompt.root; ipnat -CF -f /etc/ipnat.rules @@ -3633,35 +3642,35 @@ sh /etc/ipf.rules.script - Several options are available. When supplied with either for inbound - or for outbound, the command will retrieve - and display the appropriate list of filter rules currently - installed and in use by the kernel. To also see the rule - numbers, include . For example, - ipfstat -on displays the outbound - rules table with rule numbers: + Several options are available. When supplied with either + for inbound or for + outbound, the command will retrieve and display the + appropriate list of filter rules currently installed and in + use by the kernel. To also see the rule numbers, include + . For example, ipfstat + -on displays the outbound rules table with rule + numbers: @1 pass out on xl0 from any to any @2 block out on dc0 from any to any @3 pass out quick on dc0 proto tcp/udp from any to any keep state - Include to - prefix each rule with a count of how - many times the rule was matched. For example, - ipfstat -oh displays the outbound - internal rules table, prefixing each rule with its usage count: + Include to prefix each rule with a + count of how many times the rule was matched. For example, + ipfstat -oh displays the outbound internal + rules table, prefixing each rule with its usage count: 2451423 pass out on xl0 from any to any 354727 block out on dc0 from any to any 430918 pass out quick on dc0 proto tcp/udp from any to any keep state - To display the state table in a format similar to &man.top.1;, use - ipfstat -t. When the firewall is - under attack, this option provides the ability to identify - and see the attacking packets. The optional sub-flags give - the ability to select the destination or source IP, port, or - protocol to be monitored in real time. Refer to - &man.ipfstat.8; for details. + To display the state table in a format similar to + &man.top.1;, use ipfstat -t. When the + firewall is under attack, this option provides the ability to + identify and see the attacking packets. The optional + sub-flags give the ability to select the destination or source + IP, port, or protocol to be monitored in + real time. Refer to &man.ipfstat.8; for details. @@ -3676,16 +3685,17 @@ sh /etc/ipf.rules.script IPF provides - ipmon, which can be used to write the firewall's logging - information in a human readable format. It requires that - options IPFILTER_LOG be first added - to a custom kernel using the instructions in . - - This command is typically run in - daemon mode in order to provide a continuous system log file so that - logging of past events may be reviewed. Since &os; has a built in - &man.syslogd.8; facility to automatically rotate system logs, the default - rc.conf + ipmon, which can be used to write the + firewall's logging information in a human readable format. It + requires that options IPFILTER_LOG be first + added to a custom kernel using the instructions in . + + This command is typically run in daemon mode in order to + provide a continuous system log file so that logging of past + events may be reviewed. Since &os; has a built in + &man.syslogd.8; facility to automatically rotate system logs, + the default rc.conf ipmon_flags statement uses : @@ -3701,20 +3711,19 @@ sh /etc/ipf.rules.scriptOnce the logging facility is enabled in rc.conf and started with service - ipmon start, IPF will only - log the rules which contain the log keyword. The firewall - administrator decides which rules in the ruleset should be - logged and normally - only deny rules are logged. It is customary to include the - log keyword in the - last rule in the ruleset. This makes it possible to see all - the packets that did not match any of the rules in the - ruleset. + ipmon start, IPF will + only log the rules which contain the log + keyword. The firewall administrator decides which rules in + the ruleset should be logged and normally only deny rules are + logged. It is customary to include the + log keyword in the last rule in the + ruleset. This makes it possible to see all the packets that + did not match any of the rules in the ruleset. By default, ipmon -Ds mode uses - local0 as - the logging facility. The following logging levels can be - used to further segregate the logged data: + local0 as the logging facility. The + following logging levels can be used to further segregate the + logged data: LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block. LOG_NOTICE - packets logged which are also passed @@ -3798,11 +3807,13 @@ LOG_ERR - packets which have been logged letters corresponding to any flags that were set. Refer to &man.ipf.5; for a list of letters and their flags. - If the packet is an ICMP packet, there will be two fields - at the end: the first always being icmp and - the next being the ICMP message and sub-message type, - separated by a slash. For example: icmp 3/3 for a port - unreachable message. + If the packet is an ICMP packet, there + will be two fields at the end: the first always being + icmp and the next being the + ICMP message and sub-message type, + separated by a slash. For example: + icmp 3/3 for a port unreachable + message. - +