docs/122351: [patch] update to PF section of handbook
John Ferrell
jdferrell3 at yahoo.com
Tue Apr 1 19:10:01 UTC 2008
>Number: 122351
>Category: docs
>Synopsis: [patch] update to PF section of handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Apr 01 19:10:01 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator: John Ferrell
>Release: 7.0-RELEASE
>Organization:
>Environment:
FreeBSD fbsd.local 7.0-RELEASE FreeBSD 7.0-RELEASE #7: Mon Mar 24 17:46:10 EDT 2008 root at local:/usr/obj/usr/src/sys/JDF i386
>Description:
Attached is a diff to update the PF section of firewalls/chapter.sgml. I revised and updated the section, rewording and reorganizing parts for clarity. I also pointed out the /etc/pf.conf move in FreeBSD 7.0 (docs/121321: Handbook should reflect new pf.conf defaults) and addressed why you would want to compile PF support into the kernel. (There was a comment on the freebsd-doc list recently about compiling pfsync into the kernel.)
The updated version can be viewed here:
http://bigapps.rhsmith.umd.edu/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html
Comments/suggestions are welcome.
Thanks,
John
>How-To-Repeat:
>Fix:
Patch attached with submission follows:
--- 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>
+ <!-- 24 March 2008 -->
+ </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; 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">
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list