Attachment 85991 Details for Bug 122351 – chapter.sgml.diff.txt

chapter.sgml.diff.txt

chapter.sgml.diff.txt (text/plain), 14.51 KB, created by John Ferrell on 2008-04-08 19:03:20 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: John Ferrell

Created: 2008-04-08 19:03:20 UTC

Size: 14.51 KB

patch

obsolete

>--- chapter.sgml.orig	2008-03-28 17:07:01.000000000 -0400
>+++ chapter.sgml	2008-04-01 14:14:19.000000000 -0400
>@@ -182,6 +182,17 @@
>   </sect1>
> 
>   <sect1 id="firewalls-pf">
>+      <sect1info>    
>+        <authorgroup>
>+          <author>
>+            <firstname>John</firstname>
>+            <surname>Ferrell</surname>
>+            <contrib>Revised and updated by </contrib>
>+            
>+          </author>
>+        </authorgroup>
>+      </sect1info>
>+
>     <title>The OpenBSD Packet Filter (PF) and
>       <acronym>ALTQ</acronym></title>
> 
>@@ -192,60 +203,65 @@
>     </indexterm>
> 
>     <para>As of July 2003 the OpenBSD firewall software application
>-      known as <acronym>PF</acronym> was ported to &os; and was made
>-      available in the &os; Ports Collection; the first release that
>-      contained <acronym>PF</acronym> as an integrated part of the
>-      base system was &os;&nbsp;5.3 in November 2004.
>-      <acronym>PF</acronym> is a complete, fully featured firewall
>+      known as <acronym>PF</acronym> was ported to &os; and 
>+      made available in the &os; Ports Collection.  Released in 2004, 
>+      &os; 5.3 was the first release that contained 
>+      <acronym>PF</acronym> as an integrated part of the base system.
>+      <acronym>PF</acronym> is a complete, full-featured firewall
>       that has optional support for <acronym>ALTQ</acronym> (Alternate
>       Queuing).  <acronym>ALTQ</acronym> provides Quality of Service
>-      (<acronym>QoS</acronym>) bandwidth shaping that allows
>-      guaranteeing bandwidth to different services based on filtering
>-      rules.  The OpenBSD Project does an outstanding job of
>-      maintaining the PF User's Guide that it will not be made part of
>-      this handbook firewall section as that would just be duplicated
>-      effort.</para>
>-
>-    <para>More info can be found at the PF for &os; web site: <ulink
>-	url="http://pf4freebsd.love2party.net/"></ulink>.</para>
>-
>-    <sect2>
>-      <title>Enabling PF</title>
>-
>-      <para>PF is included in the basic &os; install for versions newer
>-	than 5.3 as a separate run time loadable module.  The system
>-	will dynamically load the PF kernel loadable module when the
>-	rc.conf statement <literal>pf_enable="YES"</literal> is used.
>-	The loadable module was created with &man.pflog.4; logging
>-	enabled.</para>
>-
>-      <note>
>-	<para>The module assumes the presence of <literal>options
>-	    INET</literal> and <literal>device bpf</literal>.  Unless
>-	  <literal>NOINET6</literal> for &os; prior to 6.0-RELEASE and
>-	  <literal>NO_INET6</literal> for later releases (for example in
>-	  &man.make.conf.5;) was defined during the build, it also
>-	  requires <literal>options INET6</literal>.</para>
>-      </note>
>+      (<acronym>QoS</acronym>) functionality.</para>
> 
>-      <para>Once the kernel module is loaded or the kernel is statically
>-	built with PF support, it is possible to enable or disable
>-	<application>pf</application> with the <command>pfctl</command>
>-	command.</para>
>-
>-      <para>This example demonstrates how to enable
>-	<application>pf</application>:</para>
>-
>-      <screen>&prompt.root; <userinput>pfctl -e</userinput></screen>
>-
>-      <para>The <command>pfctl</command> command provides a way to work
>-	with the <application>pf</application> firewall. It is a good
>-	idea to check the &man.pfctl.8; manual page to find out more
>-	information about using it.</para>
>+    <para>The OpenBSD Project does an outstanding job of
>+      maintaining the 
>+      <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>.  
>+      As such, this section of the handbook will focus on  
>+      <acronym>PF</acronym> as it pertains to &os; while providing 
>+      some general information regarding usage.  For detailed usage 
>+      information please refer to the 
>+      <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>.      
>+      </para>
>+
>+    <para>More information about <acronym>PF</acronym> for &os; 
>+      can be found at 
>+      <ulink url="http://pf4freebsd.love2party.net/"></ulink>.</para>
>+
>+    <sect2>
>+      <title>Using the PF loadable kernel module</title>
>+
>+      <para>Since the release of &os; 5.3, PF has been included in the 
>+        basic install as a separate run time loadable module.  The 
>+        system will dynamically load the PF kernel module when the 
>+        &man.rc.conf.5; statement <literal>pf_enable="YES"</literal> 
>+        is present.  However, the <acronym>PF</acronym> module will 
>+        not load if the system cannot find a <acronym>PF</acronym> 
>+        ruleset configuration file.  The default location is 
>+        <filename>/etc/pf.conf</filename>.  If your 
>+        <acronym>PF</acronym> ruleset is located somewhere else use 
>+        <option>pf_rules="<replaceable>/path/pf.rules</replaceable>"</option>
>+        to specify the location.</para>
>+
>+        <note>
>+          <para>As of &os; 7.0 the sample <filename>pf.conf</filename> that 
>+            was in <filename>/etc/</filename> has been moved to 
>+            <filename>/usr/share/examples/pf/</filename>.  For &os; versions 
>+            prior to 7.0 there is an <filename>/etc/pf.conf</filename> by 
>+            default.</para>
>+        </note>
>+
>+      <para>The <acronym>PF</acronym> module can also be loaded manually 
>+        from the command line:</para>
>+
>+      <screen>&prompt.root; <userinput>kldload pf.ko</userinput></screen>
>+
>+      <para>The loadable module was created with &man.pflog.4; enabled 
>+         which provides support for logging.  If you need other 
>+         <acronym>PF</acronym> features you will need to compile 
>+         <acronym>PF</acronym> support into the kernel.</para>  
>     </sect2>
> 
>     <sect2>
>-      <title>Kernel options</title>
>+      <title>PF kernel options</title>
> 
>       <indexterm>
> 	<primary>kernel options</primary>
>@@ -265,22 +281,27 @@
> 	<secondary>device pfsync</secondary>
>       </indexterm>
> 
>-      <para>It is not a mandatory requirement that you enable PF by
>-	compiling the following options into the &os; kernel.  It is
>-	only presented here as background information.  Compiling PF
>-	into the kernel causes the loadable module to never be
>-	used.</para>
>-
>-      <para>Sample kernel config PF option statements are in the
>-	<filename>/usr/src/sys/conf/NOTES</filename> kernel source and
>-	are reproduced here:</para>
>+      <para>While it is not necessary that you compile
>+        <acronym>PF</acronym> support into the &os; kernel, you may want 
>+        to do so to take advantage of one of PF's advanced features that 
>+        is not included in the loadable module, namely &man.pfsync.4;.  
>+        pfsync is a pseudo-device that exposes certain changes to
>+        the state table used by <acronym>PF</acronym>.  pfsync can be 
>+        paired with &man.carp.4; to create failover firewalls using 
>+        <acronym>PF</acronym>.  More information on 
>+        <acronym>CARP</acronym> can be found in 
>+        <link linkend="carp">chapter 29</link> of the handbook.</para>
>+
>+      <para>The <acronym>PF</acronym> kernel options can be found in 
>+	<filename>/usr/src/sys/conf/NOTES</filename> and are reproduced 
>+        below:</para>
> 
>       <programlisting>device pf
> device pflog
> device pfsync</programlisting>
> 
>       <para><literal>device pf</literal> enables support for the
>-	<quote>Packet Filter</quote> firewall.</para>
>+	<quote>Packet Filter</quote> firewall (&man.pf.4;).</para>
> 
>       <para><literal>device pflog</literal> enables the optional
> 	&man.pflog.4; pseudo network device which can be used to log
>@@ -288,21 +309,15 @@
> 	can be used to store the logging information to disk.</para>
> 
>       <para><literal>device pfsync</literal> enables the optional
>-	&man.pfsync.4; pseudo network device that is used to monitor
>-	<quote>state changes</quote>.  As this is not part of the
>-	loadable module one has to build a custom kernel to use
>-	it.</para>
>-
>-      <para>These settings will take effect only after you have built
>-	and installed a kernel with them set.</para>
>+	&man.pfsync.4; pseudo-network device that is used to monitor
>+	<quote>state changes</quote>.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Available rc.conf Options</title>
> 
>-      <para>You need the following statements in
>-	<filename>/etc/rc.conf</filename> to activate PF at boot
>-	time:</para>
>+      <para>The following &man.rc.conf.5; statements configure
>+	<acronym>PF</acronym> and &man.pflog.4; at boot:</para>
> 
>       <programlisting>pf_enable="YES"                 # Enable PF (load module if required)
> pf_rules="/etc/pf.conf"         # rules definition file for pf
>@@ -312,22 +327,110 @@
> pflog_flags=""                  # additional flags for pflogd startup</programlisting>
> 
>       <para>If you have a LAN behind this firewall and have to forward
>-	packets for the computers in the LAN or want to do NAT, you
>-	have to enable the following option as well:</para>
>+	packets for the computers on the LAN or want to do NAT, you
>+	will need the following option as well:</para>
> 
>       <programlisting>gateway_enable="YES"            # Enable as LAN gateway</programlisting>
>     </sect2>
> 
>     <sect2>
>+      <title>Creating Filtering Rules</title>
>+
>+      <para><acronym>PF</acronym> reads its configuration rules from 
>+        &man.pf.conf.5; (<filename>/etc/pf.conf</filename> by 
>+        default) and it modifies, drops, or passes packets according to 
>+        the rules or definitions specified there.  The &os; 
>+        installation includes several sample files located in 
>+        <filename>/usr/share/examples/pf/</filename>.  Please refer to 
>+        the <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink> 
>+        for complete coverage of <acronym>PF</acronym> rulesets.</para>
>+
>+      <warning>
>+	<para>When browsing the <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>, 
>+          please keep in mind that different versions of &os; contain 
>+          different versions of PF:</para>
>+
>+        <itemizedlist>
>+          <listitem>
>+            <simpara>&os; 5.x - <acronym>PF</acronym> is at OpenBSD 3.5</simpara>
>+            </listitem>
>+
>+          <listitem>
>+            <simpara>&os; 6.x - <acronym>PF</acronym> is at OpenBSD 3.7</simpara>
>+            </listitem>
>+
>+          <listitem>
>+            <simpara>&os; 7.x - <acronym>PF</acronym> is at OpenBSD 4.1</simpara>
>+            </listitem>
>+        </itemizedlist>
>+      </warning>
>+
>+      <para>The &a.pf; is a good place to ask questions about
>+	configuring and running the <acronym>PF</acronym>
>+	firewall.  Do not forget to check the mailing list archives
>+	before asking questions!</para>
>+    </sect2>
>+
>+    <sect2>
>+      <title>Working with PF</title>
>+
>+      <para>Use &man.pfctl.8; to control <acronym>PF</acronym>.  Below 
>+        are some useful commands (be sure to review the &man.pfctl.8; 
>+        man page for all available options):
>+	</para>
>+
>+        <informaltable frame="none" pgwide="1">
>+          <tgroup cols="2">
>+            <thead>
>+              <row>
>+                <entry>Command</entry>
>+                <entry>Purpose</entry>
>+              </row>
>+            </thead>
>+
>+            <tbody>
>+              <row>
>+                <entry><command>pfctl -e</command></entry>
>+                <entry>Enable PF</entry>
>+              </row>
>+
>+              <row>
>+                <entry><command>pfctl -d</command></entry>
>+                <entry>Disable PF</entry>
>+              </row>
>+
>+              <row>
>+                <entry><command>pfctl -F all -f /etc/pf.conf</command></entry>
>+                <entry>Flush all rules (nat, filter, state, table, etc.) and reload from the file <filename>/etc/pf.conf</filename></entry>
>+              </row>
>+
>+              <row>
>+                <entry><command>pfctl -s [ rules | nat | state ]</command></entry>
>+                <entry>Report on the  filter rules, nat rules, or state table</entry>
>+              </row>
>+
>+              <row>
>+                <entry><command>pfctl -vnf /etc/pf.conf</command></entry>
>+                <entry>Check <filename>/etc/pf.conf</filename> for errors, but do not load ruleset</entry>
>+              </row>
>+
>+            </tbody>
>+          </tgroup>
>+        </informaltable>
>+    </sect2>
>+
>+    <sect2>
>       <title>Enabling <acronym>ALTQ</acronym></title>
> 
>-      <para><acronym>ALTQ</acronym> is only available by compiling the
>-	options into the &os; Kernel.  <acronym>ALTQ</acronym> is not
>-	supported by all of the available network card drivers.	 Please
>-	see the &man.altq.4; manual page for a list of drivers that are
>-	supported in your release of &os;.  The following options will
>-	enable <acronym>ALTQ</acronym> and add additional
>-	functionality.</para>
>+      <para><acronym>ALTQ</acronym> is only available by compiling 
>+        support for it into the &os; kernel.  <acronym>ALTQ</acronym> is 
>+        not supported by all of the available network card drivers.	 
>+        Please see the &man.altq.4; manual page for a list of drivers 
>+        that are supported in your release of &os;.</para>
>+
>+      <para>The following kernel options will enable 
>+        <acronym>ALTQ</acronym> and add additional functionality:
>+        </para>
> 
>       <programlisting>options         ALTQ
> options         ALTQ_CBQ        # Class Bases Queuing (CBQ)
>@@ -373,36 +476,6 @@
> 	This option is required on <acronym>SMP</acronym>
> 	systems.</para>
>     </sect2>
>-
>-    <sect2>
>-      <title>Creating Filtering Rules</title>
>-
>-      <para>The Packet Filter reads its configuration rules from the
>-	&man.pf.conf.5; file and it modifies, drops or passes packets
>-	according to the rules or definitions specified there.  The &os;
>-	installation comes with a default
>-	<filename>/etc/pf.conf</filename> which contains useful examples
>-	and explanations.</para>
>-
>-      <para>Although &os; has its own <filename>/etc/pf.conf</filename>
>-	the syntax is the same as one used in OpenBSD.  A great
>-	resource for configuring the <application>pf</application>
>-	firewall has been written by OpenBSD team and is available at
>-	<ulink url="http://www.openbsd.org/faq/pf/"></ulink>.</para>
>-
>-      <warning>
>-	<para>When browsing the pf user's guide, please keep in mind that
>-     different versions of &os; contain different versions of pf.  The
>-     <application>pf</application> firewall in &os; 5.X is at the level
>-     of OpenBSD version 3.5 and in &os; 6.X is at the level of OpenBSD
>-     version 3.7.</para>
>-      </warning>
>-
>-      <para>The &a.pf; is a good place to ask questions about
>-	configuring and running the <application>pf</application>
>-	firewall.  Do not forget to check the mailing list archives
>-	before asking questions.</para>
>-    </sect2>
>   </sect1>
> 
>   <sect1 id="firewalls-ipf">

Actions: View

Attachments on bug 122351: 85990 | 85991