From owner-svn-doc-head@FreeBSD.ORG Fri Feb 14 21:22:51 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 92364236; Fri, 14 Feb 2014 21:22:51 +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 7A775187B; Fri, 14 Feb 2014 21:22:51 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1ELMp8Q042237; Fri, 14 Feb 2014 21:22:51 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1ELMpNH042236; Fri, 14 Feb 2014 21:22:51 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402142122.s1ELMpNH042236@svn.freebsd.org> From: Dru Lavigne Date: Fri, 14 Feb 2014 21:22:51 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43930 - 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-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 14 Feb 2014 21:22:51 -0000 Author: dru Date: Fri Feb 14 21:22:51 2014 New Revision: 43930 URL: http://svnweb.freebsd.org/changeset/doc/43930 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 Fri Feb 14 21:04:15 2014 (r43929) +++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml Fri Feb 14 21:22:51 2014 (r43930) @@ -545,85 +545,84 @@ options ALTQ_PRIQ # Priori real-world usage of PF's many features. - The simplest possible ruleset is for a single machine - that does not run any services and which needs access to one - network, which may be the Internet. To create this minimal - ruleset, edit - /etc/pf.conf so it looks like this: + The simplest possible ruleset is for a single machine + that does not run any services and which needs access to one + network, which may be the Internet. To create this minimal + ruleset, edit /etc/pf.conf so it looks + like this: - block in all + block in all pass out all keep state - The first rule denies all incoming traffic by default. - The second rule allows - connections created by this system - to pass out, while retaining state information on those - connections. This state information allows return - traffic for those connections to pass back and - should only be used on machines that can be - trusted. The ruleset can be loaded with: - - &prompt.root; pfctl -e ; pfctl -f /etc/pf.conf - - In addition to keeping state, - PF provides - lists and - macros which can be defined for use - when creating rules. Macros can include lists and need to be defined - before use. As an example, insert these lines at the - very top of the ruleset: + The first rule denies all incoming traffic by default. + The second rule allows connections created by this system to + pass out, while retaining state information on those + connections. This state information allows return traffic for + those connections to pass back and should only be used on + machines that can be trusted. The ruleset can be loaded + with: + + &prompt.root; pfctl -e ; pfctl -f /etc/pf.conf + + In addition to keeping state, + PF provides + lists and + macros which can be defined for use + when creating rules. Macros can include lists and need to be + defined before use. As an example, insert these lines at the + very top of the ruleset: - tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }" + tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }" udp_services = "{ domain }" - PF understands port - names as well as port numbers, as long as the names are listed - in /etc/services. This example - creates two macros. The first is a list of seven - TCP port names and the second is one - UDP port name. Once defined, macros can - be used in rules. In this example, all traffic is blocked - except for the connections initiated by this system for the - seven specified TCP services and the one - specified UDP service: + PF understands port names as + well as port numbers, as long as the names are listed in + /etc/services. This example creates two + macros. The first is a list of seven + TCP port names and the second is one + UDP port name. Once defined, macros can be + used in rules. In this example, all traffic is blocked except + for the connections initiated by this system for the seven + specified TCP services and the one + specified UDP service: - tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }" + tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }" udp_services = "{ domain }" block all pass out proto tcp to any port $tcp_services keep state pass proto udp to any port $udp_services keep state - Even though UDP is considered to be - a stateless protocol, PF - is able to track some state information. For example, when a - UDP request is passed which - asks a name server about a domain name, PF - will watch for the response in order to pass it back. - - Whenever an edit is made to a ruleset, the new rules - must be loaded so they can be used: - - &prompt.root; pfctl -f /etc/pf.conf + Even though UDP is considered to be a + stateless protocol, PF is able to + track some state information. For example, when a + UDP request is passed which asks a name + server about a domain name, PF will + watch for the response in order to pass it back. + + Whenever an edit is made to a ruleset, the new rules must + be loaded so they can be used: + + &prompt.root; pfctl -f /etc/pf.conf + + If there are no syntax errors, pfctl + will not output any messages during the rule load. Rules can + also be tested before attempting to load them: + + &prompt.root; pfctl -nf /etc/pf.conf + + Including causes the rules to be + interpreted only, but not loaded. This provides an + opportunity to correct any errors. At all times, the last + valid ruleset loaded will be enforced until either + PF is disabled or a new ruleset is + loaded. - If there are no syntax - errors, pfctl will not output any - messages during the rule load. Rules can also be tested before attempting to load them: - - &prompt.root; pfctl -nf /etc/pf.conf - - Including causes the rules to be interpreted - only, but not loaded. This provides an opportunity - to correct any errors. At all times, the last - valid ruleset loaded will be enforced until either - PF is disabled or a new ruleset - is loaded. - - - Adding to a - pfctl ruleset verify or load will display the fully parsed rules - exactly the way they will be loaded. This is extremely - useful when debugging rules. - + + Adding to a pfctl + ruleset verify or load will display the fully parsed rules + exactly the way they will be loaded. This is extremely + useful when debugging rules. + A Simple Gateway with NAT @@ -635,111 +634,109 @@ pass proto udp to any port $udp_services separate network. For example, one connection is to the Internet and the other is to the internal network. - It is reasonable to think that for stateful traffic to - pass from the network connected to - xl1 to hosts on the network - connected to xl0, a rule like - this is needed: - - pass in on xl1 from xl1:network to xl0:network port $ports keep state - - However, the to keyword does - guarantee passage all the way from source to destination. This rule - only lets the traffic pass in to the gateway on - the internal interface. To let the packets go - further, a matching rule is needed: - - pass out on xl0 from xl1:network to xl0:network port $ports keep state - - These rules will work, but they will not necessarily - achieve the desired effect. - - Rules this specific are rarely needed. A - better rule says: - - pass from xl1:network to any port $ports keep state - - This provides local network access to the Internet and - leaves the detective work to the - antispoof and - scrub code. - - For a busy network admin, a readable ruleset is a - safer ruleset. For the remainder of this section, with some - exceptions, we will keep the rules as simple as possible - for readability. - - Above, we introduced the - interface:network notation. That is a - nice piece of shorthand, but the ruleset can be made even - more readable and maintainable by taking the macro use a - tiny bit further. - - For example, a $localnet macro - could be defined as the network directly attached to your - internal interface ($xl1:network in the - examples above). - - Alternatively, the definition of - $localnet could be changed to an - IP address/netmask notation to denote - a network, such as 192.168.100.1/24 for - a subnet of private addresses. - - If required, $localnet could even - be defined as a list of networks. Whatever the specific - needs, a sensible $localnet definition - and a typical pass rule of the type - - pass from $localnet to any port $ports keep state - - could end up saving you a few headaches. We will - stick to that convention from here on. - - First, we need to turn on gatewaying in order to let - the machine forward the network traffic it receives on one - interface to other networks via a separate interface. - Initially we will do this on the command line with - &man.sysctl.8;, for traditional - IP version four. - - &prompt.root; sysctl net.inet.ip.forwarding=1 - - If we need to forward IP version - six traffic, the command is - - &prompt.root; sysctl net.inet6.ip6.forwarding=1 - - In order for this to continue working after the - computer has been restarted at some time in the future, - enter these settings into - /etc/rc.conf: + It is reasonable to think that for stateful traffic to + pass from the network connected to xl1 + to hosts on the network connected to + xl0, a rule like this is needed: + + pass in on xl1 from xl1:network to xl0:network port $ports keep state + + However, the to keyword does + guarantee passage all the way from source to destination. + This rule only lets the traffic pass in to the gateway on + the internal interface. To let the packets go further, a + matching rule is needed: + + pass out on xl0 from xl1:network to xl0:network port $ports keep state + + These rules will work, but they will not necessarily + achieve the desired effect. + + Rules this specific are rarely needed. A better rule + says: + + pass from xl1:network to any port $ports keep state + + This provides local network access to the Internet and + leaves the detective work to the + antispoof and + scrub code. + + For a busy network admin, a readable ruleset is a safer + ruleset. For the remainder of this section, with some + exceptions, we will keep the rules as simple as possible + for readability. + + Above, we introduced the + interface:network notation. That is a + nice piece of shorthand, but the ruleset can be made even + more readable and maintainable by taking the macro use a + tiny bit further. + + For example, a $localnet macro could + be defined as the network directly attached to your + internal interface ($xl1:network in the + examples above). + + Alternatively, the definition of + $localnet could be changed to an + IP address/netmask notation to denote + a network, such as 192.168.100.1/24 for + a subnet of private addresses. + + If required, $localnet could even be + defined as a list of networks. Whatever the specific needs, + a sensible $localnet definition and a + typical pass rule of the type + + pass from $localnet to any port $ports keep state + + could end up saving you a few headaches. We will stick + to that convention from here on. + + First, we need to turn on gatewaying in order to let the + machine forward the network traffic it receives on one + interface to other networks via a separate interface. + Initially we will do this on the command line with + &man.sysctl.8;, for traditional IP version + four. + + &prompt.root; sysctl net.inet.ip.forwarding=1 + + If we need to forward IP version + six traffic, the command is + + &prompt.root; sysctl net.inet6.ip6.forwarding=1 + + In order for this to continue working after the + computer has been restarted at some time in the future, + enter these settings into + /etc/rc.conf: - gateway_enable="YES" #for ipv4 + gateway_enable="YES" #for ipv4 ipv6_gateway_enable="YES" #for ipv6 - Use ifconfig -a, or - ifconfig - interface_name to - find out if both of the interfaces to be used are up and - running. - - If all traffic initiated by machines on the inside is - to be allowed, /etc/pf.conf could - look roughly like this - - For dialup users, the external interface is the - tun0 pseudo-device. Broadband - users such as ADSL subscribers tend to have an - Ethernet interface to play with, however for a - significant subset of ADSL users, specifically those - using PPP over Ethernet (PPPoE), the correct external - interface will be the tun0 - pseudo-device, not the physical Ethernet - interface. - : + Use ifconfig -a, or + ifconfig interface_name to find out if + both of the interfaces to be used are up and + running. + + If all traffic initiated by machines on the inside is to + be allowed, /etc/pf.conf could look + roughly like this + + For dialup users, the external interface is the + tun0 pseudo-device. Broadband + users such as ADSL subscribers tend to have an + Ethernet interface to play with, however for a + significant subset of ADSL users, specifically those + using PPP over Ethernet (PPPoE), the correct external + interface will be the tun0 + pseudo-device, not the physical Ethernet + interface. + : - ext_if = "xl0" # macro for external interface - use tun0 for PPPoE + ext_if = "xl0" # macro for external interface - use tun0 for PPPoE int_if = "xl1" # macro for internal interface localnet = $int_if:network # ext_if IP address could be dynamic, hence ($ext_if) @@ -747,77 +744,77 @@ nat on $ext_if from $localnet to any -&g block all pass from { lo0, $localnet } to any keep state - Note the use of macros to assign logical names to the - network interfaces. Here 3Com cards are used, but this is - the last time during this tutorial we will find this of - any interest whatsoever. In truly simple setups like this - one, we may not gain very much by using macros like these, - but once the rulesets grow somewhat larger, you will - learn to appreciate the readability this provides. - - Also note the nat rule. This is - where we handle the network address translation from the - non-routable address inside the local net to the sole - official address we assume has been assigned. - - The parentheses surrounding the last part of the nat - rule ($ext_if) are there to compensate - for the possibility that the IP address of the external - interface may be dynamically assigned. This detail will - ensure that network traffic runs without serious - interruptions even if the external IP address - changes. - - On the other hand, this ruleset probably allows more - traffic to pass out of the network than actually desired. - One reasonable setup could contain the macro + Note the use of macros to assign logical names to the + network interfaces. Here 3Com cards are used, but this is + the last time during this tutorial we will find this of + any interest whatsoever. In truly simple setups like this + one, we may not gain very much by using macros like these, + but once the rulesets grow somewhat larger, you will + learn to appreciate the readability this provides. + + Also note the nat rule. This is + where we handle the network address translation from the + non-routable address inside the local net to the sole + official address we assume has been assigned. + + The parentheses surrounding the last part of the nat + rule ($ext_if) are there to compensate + for the possibility that the IP address of the external + interface may be dynamically assigned. This detail will + ensure that network traffic runs without serious + interruptions even if the external IP address + changes. + + On the other hand, this ruleset probably allows more + traffic to pass out of the network than actually desired. + One reasonable setup could contain the macro - client_out = "{ ftp-data, ftp, ssh, domain, pop3, auth, nntp, http, \ + client_out = "{ ftp-data, ftp, ssh, domain, pop3, auth, nntp, http, \ https, cvspserver, 2628, 5999, 8000, 8080 }" - and the main pass rule + and the main pass rule - pass inet proto tcp from $localnet to any port $client_out \ + pass inet proto tcp from $localnet to any port $client_out \ flags S/SA keep state - In addition, we have a few other pass rules. One pass rule which is useful for - administering machines remotely - is: - - pass in inet proto tcp to $ext_if port ssh - - Lastly we need to make the - name service work for our clients: - - udp_services = "{ domain, ntp }" - - This is supplemented with a rule which passes the - traffic we want through our firewall: - - pass quick inet proto { tcp, udp } to any port $udp_services keep state - - Note the quick keyword in this - rule. We have started writing rulesets which consist of - several rules, and it is time to take a look at the - relationships between the rules in a ruleset. The rules - are evaluated from top to bottom, in the sequence they are - written in the configuration file. For each packet or - connection evaluated by PF, - the last matching rule in the rule - set is the one which is applied. The - quick keyword offers an escape from the - ordinary sequence. When a packet matches a quick rule, - the packet is treated according to the present rule. The - rule processing stops without considering any further - rules which might have matched the packet. This is very - useful when a few isolated exceptions to the general rules - are needed. - - This rule also takes care of NTP, - which is used for time synchronization. One thing common - to both protocols is that they may under certain - circumstances communicate alternately over TCP and - UDP. + In addition, we have a few other pass rules. One pass + rule which is useful for administering machines remotely + is: + + pass in inet proto tcp to $ext_if port ssh + + Lastly we need to make the name service work for our + clients: + + udp_services = "{ domain, ntp }" + + This is supplemented with a rule which passes the + traffic we want through our firewall: + + pass quick inet proto { tcp, udp } to any port $udp_services keep state + + Note the quick keyword in this + rule. We have started writing rulesets which consist of + several rules, and it is time to take a look at the + relationships between the rules in a ruleset. The rules + are evaluated from top to bottom, in the sequence they are + written in the configuration file. For each packet or + connection evaluated by PF, + the last matching rule in the rule + set is the one which is applied. The + quick keyword offers an escape from the + ordinary sequence. When a packet matches a quick rule, + the packet is treated according to the present rule. The + rule processing stops without considering any further + rules which might have matched the packet. This is very + useful when a few isolated exceptions to the general rules + are needed. + + This rule also takes care of NTP, + which is used for time synchronization. One thing common + to both protocols is that they may under certain + circumstances communicate alternately over TCP and + UDP. @@ -870,94 +867,94 @@ pass from { lo0, $localnet } to any keep program which is written specifically for this purpose. - Enabling FTP transfers through your - gateway is amazingly simple, thanks to the - FTP proxy program (called - &man.ftp-proxy.8;) included in the base system on &os; and - other systems which offer - PF. - - The FTP protocol being what it is, - the proxy needs to dynamically insert rules in your rule - set. &man.ftp-proxy.8; interacts with your configuration - via a set of anchors where the proxy inserts and deletes - the rules it constructs to handle your - FTP traffic. + Enabling FTP transfers through your + gateway is amazingly simple, thanks to the + FTP proxy program (called + &man.ftp-proxy.8;) included in the base system on &os; and + other systems which offer + PF. + + The FTP protocol being what it is, + the proxy needs to dynamically insert rules in your rule + set. &man.ftp-proxy.8; interacts with your configuration + via a set of anchors where the proxy inserts and deletes + the rules it constructs to handle your + FTP traffic. - To enable &man.ftp-proxy.8;, add this line to + To enable &man.ftp-proxy.8;, add this line to /etc/rc.conf: - ftpproxy_enable="YES" + ftpproxy_enable="YES" - Starting the proxy manually by running - /usr/sbin/ftp-proxy allows testing of - the PF configuration changes we - are about to make. - - For a basic configuration, only three elements need to - be added to /etc/pf.conf. First, the - anchors: + Starting the proxy manually by running + /usr/sbin/ftp-proxy allows testing of + the PF configuration changes we + are about to make. + + For a basic configuration, only three elements need to + be added to /etc/pf.conf. First, the + anchors: - nat-anchor "ftp-proxy/*" + nat-anchor "ftp-proxy/*" rdr-anchor "ftp-proxy/*" - The proxy will insert the rules it generates for the - FTP sessions here. A pass rule is - needed to let FTP traffic in to the - proxy. - - Now for the actual redirection. Redirection rules and - NAT rules fall into the same rule - class. These rules may be referenced directly by other - rules, and filtering rules may depend on these rules. - Logically, rdr and - nat rules need to be defined before the - filtering rules. - - We insert our rdr rule immediately - after the nat rule in - /etc/pf.conf - - rdr pass on $int_if proto tcp from any to any port ftp -> 127.0.0.1 port 8021 - - In addition, the redirected traffic must be allowed to - pass. We achieve this with - - pass out proto tcp from $proxy to any port ftp - - where $proxy expands to the address - the proxy daemon is bound to. - - Save pf.conf, then load the new - rules with - - &prompt.root; pfctl -f /etc/pf.conf - - At this point, users will probably begin noticing - that FTP works before they have been - told. - - This example covers a basic setup where the clients in - the local net need to contact FTP - servers elsewhere. The basic configuration here should - work well with most combinations of FTP - clients and servers. As shown in the man page, the - proxy's behavior can be changed in various ways by adding - options to the ftpproxy_flags= line. - Some clients or servers may have specific quirks that must - be compensated for in the configuration, or there may be a - need to integrate the proxy in specific ways such as - assigning FTP traffic to a specific - queue. For these and other finer points of - &man.ftp-proxy.8; configuration, start by studying the man - page. - - For ways to run an FTP server - protected by PF and - &man.ftp-proxy.8;, look into running a separate - ftp-proxy in reverse mode (using - ), on a separate port with its own - redirecting pass rule. + The proxy will insert the rules it generates for the + FTP sessions here. A pass rule is + needed to let FTP traffic in to the + proxy. + + Now for the actual redirection. Redirection rules and + NAT rules fall into the same rule + class. These rules may be referenced directly by other + rules, and filtering rules may depend on these rules. + Logically, rdr and + nat rules need to be defined before the + filtering rules. + + We insert our rdr rule immediately + after the nat rule in + /etc/pf.conf + + rdr pass on $int_if proto tcp from any to any port ftp -> 127.0.0.1 port 8021 + + In addition, the redirected traffic must be allowed to + pass. We achieve this with + + pass out proto tcp from $proxy to any port ftp + + where $proxy expands to the address + the proxy daemon is bound to. + + Save pf.conf, then load the new + rules with + + &prompt.root; pfctl -f /etc/pf.conf + + At this point, users will probably begin noticing + that FTP works before they have been + told. + + This example covers a basic setup where the clients in + the local net need to contact FTP + servers elsewhere. The basic configuration here should + work well with most combinations of FTP + clients and servers. As shown in the man page, the + proxy's behavior can be changed in various ways by adding + options to the ftpproxy_flags= line. + Some clients or servers may have specific quirks that must + be compensated for in the configuration, or there may be a + need to integrate the proxy in specific ways such as + assigning FTP traffic to a specific + queue. For these and other finer points of + &man.ftp-proxy.8; configuration, start by studying the man + page. + + For ways to run an FTP server + protected by PF and + &man.ftp-proxy.8;, look into running a separate + ftp-proxy in reverse mode (using + ), on a separate port with its own + redirecting pass rule. @@ -1011,36 +1008,36 @@ rdr-anchor "ftp-proxy/*" - The obvious question then becomes, if - ICMP is such a good and useful thing, - should we not let it all through, all the time? The - answer is It depends. - - Letting diagnostic traffic pass unconditionally of - course makes debugging easier, but also makes it - relatively easy for others to extract information about - your network. That means that a rule like - - pass inet proto icmp from any to any - - might not be optimal if the internal workings of the - local network should be cloaked in a bit of mystery. In - all fairness it should also be said that some - ICMP traffic might be found quite - harmlessly riding piggyback on - keep state rules. - - The easiest solution could very well be to let all - ICMP traffic from the local net through - and stop probes from elsewhere at the gateway: + The obvious question then becomes, if + ICMP is such a good and useful thing, + should we not let it all through, all the time? The + answer is It depends. + + Letting diagnostic traffic pass unconditionally of + course makes debugging easier, but also makes it + relatively easy for others to extract information about + your network. That means that a rule like + + pass inet proto icmp from any to any + + might not be optimal if the internal workings of the + local network should be cloaked in a bit of mystery. In + all fairness it should also be said that some + ICMP traffic might be found quite + harmlessly riding piggyback on + keep state rules. + + The easiest solution could very well be to let all + ICMP traffic from the local net through + and stop probes from elsewhere at the gateway: - pass inet proto icmp from $localnet to any keep state + pass inet proto icmp from $localnet to any keep state pass inet proto icmp from any to $ext_if keep state - Stopping probes at the gateway might be an attractive - option anyway, but let us have a look at a few other - options which will show some of - PF's flexibility. + Stopping probes at the gateway might be an attractive + option anyway, but let us have a look at a few other + options which will show some of + PF's flexibility. Letting <command>ping</command> Through