Date: Tue, 1 Apr 2008 19:00:58 GMT From: John Ferrell <jdferrell3@yahoo.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/122351: [patch] update to PF section of handbook Message-ID: <200804011900.m31J0wAe016226@www.freebsd.org> Resent-Message-ID: <200804011910.m31JA1jf071487@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200804011900.m31J0wAe016226>