svn commit: r52936 - head/en_US.ISO8859-1/books/handbook/firewalls

Benedict Reuschling bcr at FreeBSD.org
Thu Apr 18 11:20:50 UTC 2019


Author: bcr
Date: Thu Apr 18 11:20:49 2019
New Revision: 52936
URL: https://svnweb.freebsd.org/changeset/doc/52936

Log:
  This patch updates the PF chapter regarding structure and various updates.
  
  After discussing some updates to the PF chapter with current maintainer kp@,
  I came up with the following list of changes in this patch:
  
  - Change the warning message to remove the reference to a specific PF version
  and point out that FreeBSDs pf has diverged from what's in OpenBSD.
  - Remove a link to the old pf porting efforts, which is obsolete nowadays and
  doesn't provide much value to the reader anymore
  - Change the reading flow by putting the ALTQ section at the end of the chapter.
  ALTQ with PF is not used by everyone, so having that at the end of the chapter
  is good to not overwhelm the reader too much with concepts they probably don't
  need.
  - Remove the "In order to" sentence parts which are mostly superfluous and can
  be replaced with "to" for increased readability
  - Sprinkle in some sysrc in examples where it makes sense to use it
  
  Reviewed by:	kp@
  Event:		Aberdeen hackathon 2019
  Differential Revision:	https://reviews.freebsd.org/D19939

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	Wed Apr 17 14:48:48 2019	(r52935)
+++ head/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml	Thu Apr 18 11:20:49 2019	(r52936)
@@ -313,8 +313,11 @@
     <warning>
       <para>When reading the <link
 	  xlink:href="http://www.openbsd.org/faq/pf/">PF FAQ</link>,
-	keep in mind that &os; uses the same version of
-	<application>PF</application> as OpenBSD 4.5.</para>
+	keep in mind that &os;'s version of
+	<application>PF</application> has diverged substantially from
+	the upstream OpenBSD version over the years.  Not all features
+	work the same way on &os; as they do in OpenBSD and vice
+	versa.</para>
     </warning>
 
     <para>The &a.pf; is a good place to ask questions about
@@ -322,33 +325,29 @@
       firewall.  Check the mailing list archives before asking a
       question as it may have already been answered.</para>
 
-    <para>More information about porting <application>PF</application>
-      to &os; can be found at <uri
-	xlink:href="http://pf4freebsd.love2party.net/">http://pf4freebsd.love2party.net/</uri>.</para>
-
     <para>This section of the Handbook focuses on
       <application>PF</application> as it pertains to &os;.  It
       demonstrates how to enable <application>PF</application> and
-      <application>ALTQ</application>.  It then provides several
+      <application>ALTQ</application>.  It also provides several
       examples for creating rulesets on a &os; system.</para>
 
     <sect2>
       <title>Enabling <application>PF</application></title>
 
-      <para>In order to use <application>PF</application>, its kernel
+      <para>To use <application>PF</application>, its kernel
 	module must be first loaded.  This section describes the
 	entries that can be added to <filename>/etc/rc.conf</filename>
-	in order to enable <application>PF</application>.</para>
+	to enable <application>PF</application>.</para>
 
-      <para>Start by adding the following line to
+      <para>Start by adding <literal>pf_enable=yes</literal> to
 	<filename>/etc/rc.conf</filename>:</para>
 
-      <programlisting>pf_enable="YES"</programlisting>
+      <screen>&prompt.root; <userinput>sysrc pf_enable=yes</userinput></screen>
 
       <para>Additional options, described in &man.pfctl.8;, can be
 	passed to <application>PF</application> when it is started.
-	Add this entry to  <filename>/etc/rc.conf</filename> and
-	specify any required flags between the two quotes
+	Add or change this entry in <filename>/etc/rc.conf</filename>
+	and specify any required flags between the two quotes
 	(<literal>""</literal>):</para>
 
       <programlisting>pf_flags=""                     # additional flags for pfctl startup</programlisting>
@@ -366,14 +365,14 @@
 
       <para>Logging support for <application>PF</application> is
 	provided by &man.pflog.4;.  To enable logging support, add
-	this line to <filename>/etc/rc.conf</filename>:</para>
+	<literal>pflog_enable=yes</literal> to
+	<filename>/etc/rc.conf</filename>:</para>
 
-      <programlisting>pflog_enable="YES"</programlisting>
+      <screen>&prompt.root; <userinput>sysrc pflog_enable=yes</userinput></screen>
 
-      <para>The following lines can also be added in order to
-	change the default location of the log file or to specify any
-	additional flags to pass to &man.pflog.4; when it is
-	started:</para>
+      <para>The following lines can also be added to change the
+	default location of the log file or to specify any additional
+	flags to pass to &man.pflog.4; when it is started:</para>
 
       <programlisting>pflog_logfile="/var/log/pflog"  # where pflogd should store the logfile
 pflog_flags=""                  # additional flags for pflogd startup</programlisting>
@@ -381,7 +380,7 @@ pflog_flags=""                  # additional flags for
       <para>Finally, if there is a <acronym>LAN</acronym> behind the
 	firewall and packets need to be forwarded for the computers on
 	the <acronym>LAN</acronym>, or <acronym>NAT</acronym> is
-	required, add the following option:</para>
+	required, enable the following option:</para>
 
       <programlisting>gateway_enable="YES"            # Enable as LAN gateway</programlisting>
 
@@ -523,94 +522,6 @@ device pfsync</programlisting>
 	similar to &man.top.1;.</para>
     </sect2>
 
-    <sect2>
-      <title>Enabling <application>ALTQ</application></title>
-
-      <para>On &os;, <application>ALTQ</application> can be used with
-	<application>PF</application> to provide Quality of Service
-	(<acronym>QOS</acronym>).  Once
-	<application>ALTQ</application> is enabled, queues can be
-	defined in the ruleset which determine the processing priority
-	of outbound packets.</para>
-
-      <para>Before enabling <application>ALTQ</application>, refer to
-	&man.altq.4; to determine if the drivers for the network cards
-	installed on the system support it.</para>
-
-      <para><application>ALTQ</application> is not available as a
-	loadable kernel module.  If the system's interfaces support
-	<application>ALTQ</application>, create a custom kernel using
-	the instructions in <xref linkend="kernelconfig"/>.  The
-	following kernel options are available.  The first is needed
-	to enable <application>ALTQ</application>.  At least one of
-	the other options is necessary to specify the queueing
-	scheduler algorithm:</para>
-
-      <programlisting>options         ALTQ
-options         ALTQ_CBQ        # Class Based Queuing (CBQ)
-options         ALTQ_RED        # Random Early Detection (RED)
-options         ALTQ_RIO        # RED In/Out
-options         ALTQ_HFSC       # Hierarchical Packet Scheduler (HFSC)
-options         ALTQ_PRIQ       # Priority Queuing (PRIQ)</programlisting>
-
-      <para>The following scheduler algorithms are available:</para>
-
-      <variablelist>
-	<varlistentry>
-	  <term>CBQ</term>
-	  <listitem>
-	    <para>Class Based Queuing (<acronym>CBQ</acronym>) is
-	      used to divide a connection's bandwidth into different
-	      classes or queues to prioritize traffic based on filter
-	      rules.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term>RED</term>
-	  <listitem>
-	    <para>Random Early Detection (<acronym>RED</acronym>) is
-	      used to avoid network congestion by measuring the length
-	      of the queue and comparing it to the minimum and maximum
-	      thresholds for the queue.  When the queue is over the
-	      maximum, all new packets are randomly dropped.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term>RIO</term>
-	  <listitem>
-	    <para>In Random Early Detection In and Out
-	      (<acronym>RIO</acronym>) mode, <acronym>RED</acronym>
-	      maintains multiple average queue lengths and multiple
-	      threshold values, one for each
-	      <acronym>QOS</acronym> level.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term>HFSC</term>
-	  <listitem>
-	    <para>Hierarchical Fair Service Curve Packet Scheduler
-	      (<acronym>HFSC</acronym>) is described in <uri
-		xlink:href="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html">http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html</uri>.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term>PRIQ</term>
-	  <listitem>
-	    <para>Priority Queuing (<acronym>PRIQ</acronym>) always
-	      passes traffic that is in a higher queue first.</para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>
-
-      <para>More information about the scheduling
-	algorithms and example rulesets are available at the <uri
-	  xlink:href="https://web.archive.org/web/20151109213426/http://www.openbsd.org/faq/pf/queueing.html">OpenBSD's web archive</uri>.</para>
-    </sect2>
-
     <sect2 xml:id="pf-tutorial">
       <info>
 	<title><application>PF</application> Rulesets</title>
@@ -685,7 +596,7 @@ pass proto udp to any port $udp_services keep state</p
 	track some state information.  For example, when a
 	<acronym>UDP</acronym> request is passed which asks a name
 	server about a domain name, <application>PF</application> will
-	watch for the response in order to pass it back.</para>
+	watch for the response to pass it back.</para>
 
       <para>Whenever an edit is made to a ruleset, the new rules must
 	be loaded so they can be used:</para>
@@ -723,7 +634,7 @@ pass proto udp to any port $udp_services keep state</p
 	  connected to the Internet and <filename>xl0</filename> is
 	  connected to the internal network.</para>
 
-	<para>First, enable the gateway in order to let the machine
+	<para>First, enable the gateway to let the machine
 	  forward the network traffic it receives on one interface to
 	  another interface.  This <application>sysctl</application>
 	  setting will forward <acronym>IPv4</acronym> packets:</para>
@@ -734,11 +645,12 @@ pass proto udp to any port $udp_services keep state</p
 
 	<screen>&prompt.root; <userinput>sysctl net.inet6.ip6.forwarding=1</userinput></screen>
 
-	<para>To enable these settings at system boot, add the
-	  following to <filename>/etc/rc.conf</filename>:</para>
+	<para>To enable these settings at system boot, use
+	  &man.sysrc.8; to add them to
+	  <filename>/etc/rc.conf</filename>:</para>
 
-	<programlisting>gateway_enable="YES"		#for ipv4
-ipv6_gateway_enable="YES"	#for ipv6</programlisting>
+	<screen>&prompt.root; <userinput>sysrc gateway_enable=yes</userinput>
+&prompt.root; <userinput>sysrc ipv6_gateway_enable=yes</userinput></screen>
 
 	<para>Verify with <command>ifconfig</command> that both of the
 	  interfaces are up and running.</para>
@@ -897,7 +809,7 @@ pass quick inet proto { tcp, udp } to any port $udp_se
 	  proxy program called &man.ftp-proxy.8;, which is included in
 	  the base system of &os;.  The role of the proxy is to
 	  dynamically insert and delete rules in the ruleset, using a
-	  set of anchors, in order to correctly handle
+	  set of anchors, to correctly handle
 	  <acronym>FTP</acronym> traffic.</para>
 
 	<para>To enable the <acronym>FTP</acronym> proxy, add this
@@ -1063,7 +975,7 @@ pass out on $ext_if inet proto udp from any to any por
 	  <programlisting>icmp_types = "{ echoreq, unreach }"</programlisting>
 
 	  <para>Since the pass rule already uses that macro, it does
-	    not need to be modified in order to support the new
+	    not need to be modified to support the new
 	    <acronym>ICMP</acronym> type:</para>
 
 	  <programlisting>pass inet proto icmp all icmp-type $icmp_types keep state</programlisting>
@@ -1302,11 +1214,9 @@ pass inet proto tcp from any to $localnet port $tcp_se
 
 	  <step>
 	    <para>Install the <package>mail/spamd</package> package
-	      or port.  In order to use
-	      <application>spamd</application>'s greylisting
-	      features, &man.fdescfs.5; must be mounted at <filename
-		>/dev/fd</filename>.  Add the
-	      following line to
+	      or port.  To use <application>spamd</application>'s
+	      greylisting features, &man.fdescfs.5; must be mounted at
+	      <filename>/dev/fd</filename>.  Add the following line to
 	      <filename>/etc/fstab</filename>:</para>
 
 	    <programlisting> fdescfs /dev/fd fdescfs rw 0 0</programlisting>
@@ -1444,8 +1354,8 @@ rdr pass on $ext_if inet proto tcp from !<spamd-whi
 	    xlink:href="http://www.greylisting.org/">greylisting.org</link>
 	  web site.  The most amazing thing about greylisting, apart
 	  from its simplicity, is that it still works.  Spammers and
-	  malware writers have been very slow to adapt in order to
-	  bypass this technique.</para>
+	  malware writers have been very slow to adapt to bypass this
+	  technique.</para>
 
 	<para>The basic procedure for configuring greylisting is as
 	  follows:</para>
@@ -1576,6 +1486,94 @@ antispoof for $int_if</programlisting>
 block drop in quick on $ext_if from $martians to any
 block drop out quick on $ext_if from any to $martians</programlisting>
       </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Enabling <application>ALTQ</application></title>
+
+      <para>On &os;, <application>ALTQ</application> can be used with
+	<application>PF</application> to provide Quality of Service
+	(<acronym>QOS</acronym>).  Once
+	<application>ALTQ</application> is enabled, queues can be
+	defined in the ruleset which determine the processing priority
+	of outbound packets.</para>
+
+      <para>Before enabling <application>ALTQ</application>, refer to
+	&man.altq.4; to determine if the drivers for the network cards
+	installed on the system support it.</para>
+
+      <para><application>ALTQ</application> is not available as a
+	loadable kernel module.  If the system's interfaces support
+	<application>ALTQ</application>, create a custom kernel using
+	the instructions in <xref linkend="kernelconfig"/>.  The
+	following kernel options are available.  The first is needed
+	to enable <application>ALTQ</application>.  At least one of
+	the other options is necessary to specify the queueing
+	scheduler algorithm:</para>
+
+      <programlisting>options         ALTQ
+options         ALTQ_CBQ        # Class Based Queuing (CBQ)
+options         ALTQ_RED        # Random Early Detection (RED)
+options         ALTQ_RIO        # RED In/Out
+options         ALTQ_HFSC       # Hierarchical Packet Scheduler (HFSC)
+options         ALTQ_PRIQ       # Priority Queuing (PRIQ)</programlisting>
+
+      <para>The following scheduler algorithms are available:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>CBQ</term>
+	  <listitem>
+	    <para>Class Based Queuing (<acronym>CBQ</acronym>) is
+	      used to divide a connection's bandwidth into different
+	      classes or queues to prioritize traffic based on filter
+	      rules.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>RED</term>
+	  <listitem>
+	    <para>Random Early Detection (<acronym>RED</acronym>) is
+	      used to avoid network congestion by measuring the length
+	      of the queue and comparing it to the minimum and maximum
+	      thresholds for the queue.  When the queue is over the
+	      maximum, all new packets are randomly dropped.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>RIO</term>
+	  <listitem>
+	    <para>In Random Early Detection In and Out
+	      (<acronym>RIO</acronym>) mode, <acronym>RED</acronym>
+	      maintains multiple average queue lengths and multiple
+	      threshold values, one for each
+	      <acronym>QOS</acronym> level.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>HFSC</term>
+	  <listitem>
+	    <para>Hierarchical Fair Service Curve Packet Scheduler
+	      (<acronym>HFSC</acronym>) is described in <uri
+		xlink:href="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html">http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html</uri>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>PRIQ</term>
+	  <listitem>
+	    <para>Priority Queuing (<acronym>PRIQ</acronym>) always
+	      passes traffic that is in a higher queue first.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>More information about the scheduling
+	algorithms and example rulesets are available at the <uri
+	  xlink:href="https://web.archive.org/web/20151109213426/http://www.openbsd.org/faq/pf/queueing.html">OpenBSD's web archive</uri>.</para>
     </sect2>
   </sect1>
 


More information about the svn-doc-all mailing list