Editorial pass through Tables section.

Sponsored by: iXsystems

1 files changed, 95 insertions, 166 deletions

diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
index 94de1ba226..340d352948 100644
--- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
@@ -1004,74 +1004,64 @@ pass out on $ext_if inet proto udp from any to any port 33433 >< 33626 kee
       <sect3 xml:id="pftut-tables">
 	<title>Using Tables</title>
 
-	<para>By this time it may appear that this gets awfully static
-	  and rigid.  There will after all be some kinds of data which
+	<para>Some types of data
 	  are relevant to filtering and redirection at a given time,
-	  but do not deserve to be put into a configuration file!
-	  Quite right, and <application>PF</application> offers
-	  mechanisms for handling these situations as well.  Tables
-	  are one such feature, mainly useful as lists which can be
+	  but their definition is too long to be included in the ruleset file.
+	  <application>PF</application> supports the use of tables,
+	  which are defined lists that can be
 	  manipulated without needing to reload the entire ruleset,
-	  and where fast lookups are desirable.  Table names are
-	  always enclosed in <literal>&lt; &gt;</literal>, like
+	  and which can provide fast lookups.  Table names are
+	  always enclosed within <literal>&lt; &gt;</literal>, like
 	  this:</para>
 
 	<programlisting>table &lt;clients&gt; { 192.168.2.0/24, !192.168.2.5 }</programlisting>
 
-	<para>Here, the network <literal>192.168.2.0/24</literal>
-	  is part of the table, except the address
+	<para>In this example, the <literal>192.168.2.0/24</literal> network
+	  is part of the table, except for the address
 	  <literal>192.168.2.5</literal>, which is excluded using
-	  the <literal>!</literal> operator (logical NOT).  It is
+	  the <literal>!</literal> operator.  It is
 	  also possible to load tables from files where each item is
-	  on a separate line, such as the file
-	  <filename>/etc/clients</filename>.</para>
+	  on a separate line, as seen in this example
+	  <filename>/etc/clients</filename>:</para>
 
 	<programlisting>192.168.2.0/24
 !192.168.2.5</programlisting>
 
-	<para>which in turn is used to initialize the table in
-	  <filename>/etc/pf.conf</filename>:</para>
+	<para>To refer to the file, define the table like this:</para>
 
 	<programlisting>table &lt;clients&gt; persist file "/etc/clients"</programlisting>
 
-	<para>Then, for example, one of our earlier rules can be
-	  changed to read</para>
+	<para>Once the table is defined, it can be referenced by a
+	  rule:</para>
 
 	<programlisting>pass inet proto tcp from &lt;clients&gt; to any port $client_out flags S/SA keep state</programlisting>
 
-	<para>to manage outgoing traffic from client computers.  With
-	  this in hand, the table's contents can be manipulated live,
-	  such as</para>
+	<para>A table's contents can be manipulated live, using <command>pfctl</command>.
+	  This example adds another network to the table:</para>
 
-	<screen>&prompt.root; <userinput>pfctl -t clients -T add 192.168.1/16</userinput></screen>
+	<screen>&prompt.root; <userinput>pfctl -t clients -T add 192.168.1.0/16</userinput></screen>
 
-	<para>Note that this changes the in-memory copy of the table
-	  only, meaning that the change will not survive a power
-	  failure or other reboot unless there are arrangements to
-	  store the changes.</para>
-
-	<para>One might opt to maintain the on-disk copy of the table
-	  using a &man.cron.8; job which dumps the table content to
+	<para>Note that any changes made this way will take affect now,
+	  making them ideal for testing,
+	  but will not survive a power
+	  failure or reboot.  To make the changes permanent, modify the
+	  definition of the table in the ruleset or edit the file that the
+	  table refers to.  One can maintain the on-disk copy of the table
+	  using a &man.cron.8; job which dumps the table's contents to
 	  disk at regular intervals, using a command such as
 	  <command>pfctl -t clients -T show
 	    &gt;/etc/clients</command>.  Alternatively,
-	  <filename>/etc/clients</filename> could be edited, replacing
-	  the in-memory table contents with the file data:</para>
+	  <filename>/etc/clients</filename> can be updated with
+	  the in-memory table contents:</para>
 
 	<screen>&prompt.root; <userinput>pfctl -t clients -T replace -f /etc/clients</userinput></screen>
-
-	<para>For operations performed frequently, administrators will
-	  sooner or later end up writing shell scripts for tasks
-	  such as inserting or removing items or replacing table
-	  contents.  The only real limitations lie in individual needs
-	  and creativity.</para>
       </sect3>
 
       <sect3 xml:id="pftut-overload">
-	<title>Overload Tables</title>
+	<title>Using Overload Tables to Protect <acronym>SSH</acronym></title>
 
-	<para>Those who run a Secure Shell login service which is
-	  accessible from the Internet have probably seen something
+	<para>Those who run <acronym>SSH</acronym> on an external interface
+	  have probably seen something
 	  like this in the authentication logs:</para>
 
 	<programlisting>Sep 26 03:12:34 skapet sshd[25771]: Failed password for root from 200.72.41.31 port 40992 ssh2
@@ -1081,95 +1071,68 @@ Sep 26 03:12:44 skapet sshd[29635]: Invalid user admin from 200.72.41.31
 Sep 26 03:12:44 skapet sshd[24703]: input_userauth_request: invalid user admin
 Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from 200.72.41.31 port 41484 ssh2</programlisting>
 
-	<para>And so on.  This is what a brute force attack looks
-	  like.  Essentially somebody, or more likely, a cracked
-	  computer somewhere, is trying by brute force to find a
-	  combination of user name and password which will let them
-	  into your system.</para>
-
-	<para>The simplest response would be to write a
-	  <filename>pf.conf</filename> rule which blocks all access.
-	  This leads to another class of problems, including what to
-	  do in order to let people with legitimate business on the
-	  system access it anyway.  Some might consider moving the
-	  service to another port, but then again, the ones flooding
-	  on port 22 would probably be able to scan their way to port
-	  22222 for a repeat performance.</para>
-
-	<para>Since OpenBSD 3.7, and soon after in &os; version 6.0,
-	  <application>PF</application> has offered a slightly more
-	  elegant solution.  Pass rules can be written so they
-	  maintain certain limits on what connecting hosts can do.
-	  For good measure, violators can be banished to a table of
-	  addresses which are denied some or all access.  If desired,
-	  it is even possible to drop all existing connections from
-	  machines which overreach the limits.  Here is how it is
-	  done:</para>
-
-	<para>First, set up the table.  In the tables section,
-	  add</para>
+	<para>This is indicative of a brute force attack where
+	  somebody or some program
+	  is trying to discover the
+	  user name and password which will let them
+	  into the system.</para>
+
+	<para>If external <acronym>SSH</acronym> access is needed for
+	  legitimate users, changing the default port used by
+	  <acronym>SSH</acronym> can offer some protection.
+	  However, <application>PF</application> provides a more
+	  elegant solution.  Pass rules can contain
+	  limits on what connecting hosts can do and
+	  violators can be banished to a table of
+	  addresses which are denied some or all access.  It
+	  is even possible to drop all existing connections from
+	  machines which overreach the limits.</para>
+
+	<para>To configure this, create this table in the tables section
+	  of the ruleset:</para>
 
 	<programlisting>table &lt;bruteforce&gt; persist</programlisting>
 
-	<para>Then somewhere fairly early in the ruleset, add a rule
-	  to block the bruteforcers:</para>
-
-	<programlisting>block quick from &lt;bruteforce&gt;</programlisting>
-
-	<para>And finally, the pass rule.</para>
+	<para>Then, somewhere early in the ruleset, add rules
+	  to block brute access while allowing legitimate access:</para>
 
-	<programlisting>pass inet proto tcp from any to $localnet port $tcp_services \
+	<programlisting>block quick from &lt;bruteforce&gt;
+pass inet proto tcp from any to $localnet port $tcp_services \
     flags S/SA keep state \
-    (max-src-conn 100, max-src-conn-rate 15/5, \
+    (max-src-conn <replaceable>100</replaceable>, max-src-conn-rate <replaceable>15/5</replaceable>, \
     overload &lt;bruteforce&gt; flush global)</programlisting>
 
-	<para>The first part here is identical to the main rule we
-	  constructed earlier.  The part in parentheses is the new
-	  stuff which will ease network load even further.</para>
+	<para>The part in parentheses defines the limits and the
+	  numbers should be changed to meet local requirements.  It
+	  can be read as follows:</para>
 
 	<para><literal>max-src-conn</literal> is the number of
-	  simultaneous connections allowed from one host.  In this
-	  example, it is set at 100.  Other setups may want a slightly
-	  higher or lower value.</para>
+	  simultaneous connections allowed from one host.</para>
 
 	<para><literal>max-src-conn-rate</literal> is the rate of new
-	  connections allowed from any single host, here 15
-	  connections per 5 seconds.  Again, the administrator is the
-	  one to judge what suits their setup.</para>
+	  connections allowed from any single host (<replaceable>15</replaceable>)
+	  per number of seconds (<replaceable>5</replaceable>).</para>
 
 	<para><literal>overload &lt;bruteforce&gt;</literal> means
 	  that any host which exceeds these limits gets its address
-	  added to the table <literal>bruteforce</literal>.  Our rule
-	  set blocks all traffic from addresses in the bruteforce
+	  added to the <literal>bruteforce</literal> table.  The ruleset
+	  blocks all traffic from addresses in the <literal>bruteforce</literal>
 	  table.</para>
 
 	<para>Finally, <literal>flush global</literal> says that when
-	  a host reaches the limit, that host's connections will be
-	  terminated (flushed).  The global part says that for good
-	  measure, this applies to connections which match other pass
-	  rules too.</para>
-
-	<para>The effect is dramatic.  From here on, bruteforcers
-	  more often than not will end up with
-	  <computeroutput>&quot;Fatal: timeout before
-	    authentication&quot;</computeroutput> messages, getting
-	  nowhere.</para>
+	  a host reaches the limit, that all (<literal>global</literal>) of that host's connections will be
+	  terminated (<literal>flush</literal>).</para>
 
 	<note>
 	  <para>These rules will <emphasis>not</emphasis> block slow
-	    bruteforcers, sometimes referred to as <link
-	      xlink:href="http://home.nuug.no/~peter/hailmary2013/">the
-	      Hail Mary Cloud</link>.</para>
+	    bruteforcers, as described in <link
+	      xlink:href="http://home.nuug.no/~peter/hailmary2013/">http://home.nuug.no/~peter/hailmary2013/</link>.</para>
 	</note>
 
-	<para>Once again, please keep in mind that this example rule
-	  is intended mainly as an illustration.  It is not unlikely
-	  that a particular network's needs are better served by
-	  rather different rules or combinations of rules.</para>
-
-	<para>If, for example, a generous number of connections in
-	  general are wanted, but the desire is to be a little more
-	  tight fisted when it comes to
+	<para>This example ruleset
+	  is intended mainly as an illustration.  For example, if a generous number of connections in
+	  general are wanted, but the desire is to be more
+	  restrictive when it comes to
 	  <application>ssh</application>, supplement the rule above
 	  with something like the one below, early on in the rule
 	  set:</para>
@@ -1179,87 +1142,53 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from
     (max-src-conn 15, max-src-conn-rate 5/3, \
     overload &lt;bruteforce&gt; flush global)</programlisting>
 
-	<para>It should be possible to find the set of parameters
-	  which is just right for individual situations by reading the
-	  relevant man pages and the
-	  <link xlink:href="http://www.openbsd.org/faq/pf/">PF User
-	    Guide</link>, and perhaps a bit of
-	  experimentation.</para>
-
 	<note>
 	  <title>It May Not be Necessary to Block All
 	    Overloaders</title>
 
-	  <para>It is probably worth noting at this point that the
-	    <emphasis>overload</emphasis> mechanism is a general
-	    technique which does not have to apply exclusively to the
-	    <emphasis>ssh</emphasis> service, and it is not always
-	    optimal to block all traffic from offenders
-	    entirely.</para>
+	  <para>It is worth noting that the
+	    overload mechanism is a general
+	    technique which does not apply exclusively to
+	    <acronym>SSH</acronym>, and it is not always
+	    optimal to entirely block all traffic from offenders.</para>
 
 	  <para>For example, an overload rule could be used to
 	    protect a mail service or a web service, and the overload
 	    table could be used in a rule to assign offenders to a
-	    queue with a minimal bandwidth allocation or, in the web
-	    case, to redirect to a specific web page.</para>
+	    queue with a minimal bandwidth allocation or
+	    to redirect to a specific web page.</para>
 	</note>
 
-	<sect4 xml:id="pftut-expire">
-	  <title>Expiring Table Entries with
-	    <application>pfctl</application></title>
-
-	  <para>At this point, we have tables which will be filled by
-	    our <literal>overload</literal> rules, and since we could
-	    reasonably expect our gateways to have months of uptime,
-	    the tables will grow incrementally, taking up more memory
-	    as time goes by.</para>
-
-	  <para>Sometimes an IP address that was blocked last week due
-	    to a brute force attack was in fact a dynamically assigned
-	    one, which is now assigned to a different ISP customer who
-	    has a legitimate reason to try communicating with hosts in
+	  <para>Over time, tables will be filled by
+	    overload rules and their size
+	    will grow incrementally, taking up more memory.
+	    Sometimes an <acronym>IP</acronym> address that is blocked
+	    is a dynamically assigned
+	    one, which has since been assigned to a host who
+	    has a legitimate reason to communicate with hosts in
 	    the local network.</para>
 
-	  <para>Situations like these were what caused Henning Brauer
-	    to add to <application>pfctl</application> the ability to
-	    expire table entries not referenced in a specified number
-	    of seconds (in OpenBSD 4.1).  For example, the
-	    command</para>
+	  <para>For situations like these,
+	    <application>pfctl</application> provides the ability to
+	    expire table entries.  For example, this
+	    command will remove <literal>&lt;bruteforce&gt;</literal>
+	    table entries which have not been referenced for <literal>86400</literal>
+	    seconds:</para>
 
 	  <screen>&prompt.root; <userinput>pfctl -t bruteforce -T expire 86400</userinput></screen>
 
-	  <para>will remove <literal>&lt;bruteforce&gt;</literal>
-	    table entries which have not been referenced for 86400
-	    seconds.</para>
-	</sect4>
-
-	<sect4 xml:id="pftut-expiretable">
-	  <title>The <application>expiretable</application>
-	    Tool</title>
-
-	  <para>Before <application>pfctl</application> acquired the
-	    ability to expire table entries, Henrik Gustafsson had
-	    written <application>expiretable</application>, which
+	  <para>Similar functionality is provided by
+	    <package>security/expiretable</package>, which
 	    removes table entries which have not been accessed for a
 	    specified period of time.</para>
 
-	  <para>One useful example is to use the
-	    <application>expiretable</application> program as a way of
-	    removing outdated <literal>&lt;bruteforce&gt;</literal>
-	    table entries.</para>
-
-	  <para>For example, let
-	    <application>expiretable</application> remove
+	  <para>Once installed,
+	    <application>expiretable</application> can be run to remove
 	    <literal>&lt;bruteforce&gt;</literal> table entries older
-	    than 24 hours by adding an entry containing the following
-	    to <filename>/etc/rc.local</filename>:</para>
+	    than a specified age.  This example removes all entries
+	    older than 24 hours:</para>
 
 	  <programlisting>/usr/local/sbin/expiretable -v -d -t 24h bruteforce</programlisting>
-
-	  <para><application>expiretable</application> is in the
-	    Ports&nbsp;Collection on &os; as
-	    <package>security/expiretable</package>.</para>
-	</sect4>
       </sect3>
 
       <sect3 xml:id="pftut-tools">