From owner-freebsd-doc@FreeBSD.ORG Tue Apr 1 19:10:01 2008 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7D6471065670 for ; Tue, 1 Apr 2008 19:10:01 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 5A1488FC29 for ; Tue, 1 Apr 2008 19:10:01 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.2/8.14.2) with ESMTP id m31JA1vu071488 for ; Tue, 1 Apr 2008 19:10:01 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.2/8.14.1/Submit) id m31JA1jf071487; Tue, 1 Apr 2008 19:10:01 GMT (envelope-from gnats) Resent-Date: Tue, 1 Apr 2008 19:10:01 GMT Resent-Message-Id: <200804011910.m31JA1jf071487@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, John Ferrell Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 515D6106567F for ; Tue, 1 Apr 2008 19:01:00 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21]) by mx1.freebsd.org (Postfix) with ESMTP id 3F0248FC14 for ; Tue, 1 Apr 2008 19:01:00 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.14.2/8.14.2) with ESMTP id m31J0wvw016227 for ; Tue, 1 Apr 2008 19:00:58 GMT (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.14.2/8.14.1/Submit) id m31J0wAe016226; Tue, 1 Apr 2008 19:00:58 GMT (envelope-from nobody) Message-Id: <200804011900.m31J0wAe016226@www.freebsd.org> Date: Tue, 1 Apr 2008 19:00:58 GMT From: John Ferrell To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Cc: Subject: docs/122351: [patch] update to PF section of handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 01 Apr 2008 19:10:01 -0000 >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 @@ + + + + John + Ferrell + Revised and updated by + + + + + The OpenBSD Packet Filter (PF) and <acronym>ALTQ</acronym> @@ -192,60 +203,65 @@ As of July 2003 the OpenBSD firewall software application - known as PF was ported to &os; and was made - available in the &os; Ports Collection; the first release that - contained PF as an integrated part of the - base system was &os; 5.3 in November 2004. - PF is a complete, fully featured firewall + known as PF was ported to &os; and + made available in the &os; Ports Collection. Released in 2004, + &os; 5.3 was the first release that contained + PF as an integrated part of the base system. + PF is a complete, full-featured firewall that has optional support for ALTQ (Alternate Queuing). ALTQ provides Quality of Service - (QoS) 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. - - More info can be found at the PF for &os; web site: . - - - Enabling PF - - 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 pf_enable="YES" is used. - The loadable module was created with &man.pflog.4; logging - enabled. - - - The module assumes the presence of options - INET and device bpf. Unless - NOINET6 for &os; prior to 6.0-RELEASE and - NO_INET6 for later releases (for example in - &man.make.conf.5;) was defined during the build, it also - requires options INET6. - + (QoS) functionality. - Once the kernel module is loaded or the kernel is statically - built with PF support, it is possible to enable or disable - pf with the pfctl - command. - - This example demonstrates how to enable - pf: - - &prompt.root; pfctl -e - - The pfctl command provides a way to work - with the pf firewall. It is a good - idea to check the &man.pfctl.8; manual page to find out more - information about using it. + The OpenBSD Project does an outstanding job of + maintaining the + PF FAQ. + As such, this section of the handbook will focus on + PF as it pertains to &os; while providing + some general information regarding usage. For detailed usage + information please refer to the + PF FAQ. + + + More information about PF for &os; + can be found at + . + + + Using the PF loadable kernel module + + 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 pf_enable="YES" + is present. However, the PF module will + not load if the system cannot find a PF + ruleset configuration file. The default location is + /etc/pf.conf. If your + PF ruleset is located somewhere else use + + to specify the location. + + + As of &os; 7.0 the sample pf.conf that + was in /etc/ has been moved to + /usr/share/examples/pf/. For &os; versions + prior to 7.0 there is an /etc/pf.conf by + default. + + + The PF module can also be loaded manually + from the command line: + + &prompt.root; kldload pf.ko + + The loadable module was created with &man.pflog.4; enabled + which provides support for logging. If you need other + PF features you will need to compile + PF support into the kernel. - Kernel options + PF kernel options kernel options @@ -265,22 +281,27 @@ device pfsync - 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. - - Sample kernel config PF option statements are in the - /usr/src/sys/conf/NOTES kernel source and - are reproduced here: + While it is not necessary that you compile + PF 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 PF. pfsync can be + paired with &man.carp.4; to create failover firewalls using + PF. More information on + CARP can be found in + chapter 29 of the handbook. + + The PF kernel options can be found in + /usr/src/sys/conf/NOTES and are reproduced + below: device pf device pflog device pfsync device pf enables support for the - Packet Filter firewall. + Packet Filter firewall (&man.pf.4;). device pflog 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. device pfsync enables the optional - &man.pfsync.4; pseudo network device that is used to monitor - state changes. As this is not part of the - loadable module one has to build a custom kernel to use - it. - - These settings will take effect only after you have built - and installed a kernel with them set. + &man.pfsync.4; pseudo-network device that is used to monitor + state changes. Available rc.conf Options - You need the following statements in - /etc/rc.conf to activate PF at boot - time: + The following &man.rc.conf.5; statements configure + PF and &man.pflog.4; at boot: 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 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: + packets for the computers on the LAN or want to do NAT, you + will need the following option as well: gateway_enable="YES" # Enable as LAN gateway + Creating Filtering Rules + + PF reads its configuration rules from + &man.pf.conf.5; (/etc/pf.conf 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 + /usr/share/examples/pf/. Please refer to + the PF FAQ + for complete coverage of PF rulesets. + + + When browsing the PF FAQ, + please keep in mind that different versions of &os; contain + different versions of PF: + + + + &os; 5.x - PF is at OpenBSD 3.5 + + + + &os; 6.x - PF is at OpenBSD 3.7 + + + + &os; 7.x - PF is at OpenBSD 4.1 + + + + + The &a.pf; is a good place to ask questions about + configuring and running the PF + firewall. Do not forget to check the mailing list archives + before asking questions! + + + + Working with PF + + Use &man.pfctl.8; to control PF. Below + are some useful commands (be sure to review the &man.pfctl.8; + man page for all available options): + + + + + + + Command + Purpose + + + + + + pfctl -e + Enable PF + + + + pfctl -d + Disable PF + + + + pfctl -F all -f /etc/pf.conf + Flush all rules (nat, filter, state, table, etc.) and reload from the file /etc/pf.conf + + + + pfctl -s [ rules | nat | state ] + Report on the filter rules, nat rules, or state table + + + + pfctl -vnf /etc/pf.conf + Check /etc/pf.conf for errors, but do not load ruleset + + + + + + + + Enabling <acronym>ALTQ</acronym> - ALTQ is only available by compiling the - options into the &os; Kernel. ALTQ 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 ALTQ and add additional - functionality. + ALTQ is only available by compiling + support for it into the &os; kernel. ALTQ 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 kernel options will enable + ALTQ and add additional functionality: + options ALTQ options ALTQ_CBQ # Class Bases Queuing (CBQ) @@ -373,36 +476,6 @@ This option is required on SMP systems. - - - Creating Filtering Rules - - 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 - /etc/pf.conf which contains useful examples - and explanations. - - Although &os; has its own /etc/pf.conf - the syntax is the same as one used in OpenBSD. A great - resource for configuring the pf - firewall has been written by OpenBSD team and is available at - . - - - When browsing the pf user's guide, please keep in mind that - different versions of &os; contain different versions of pf. The - pf 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. - - - The &a.pf; is a good place to ask questions about - configuring and running the pf - firewall. Do not forget to check the mailing list archives - before asking questions. - >Release-Note: >Audit-Trail: >Unformatted: