New firewall section (was: Re: HEADS UP: doc/ slush begins)

[Giorgos Keramidas]

On 2004-09-20 12:06, Ceri Davies <ceri at submonkey.net> wrote:
>
> Referring to ... http://freebsd.so14k.com/firewall/
>
> Is everyone else happy (doceng/translators) if this were to go in before
> the release?

FWIW, the new text is definitely a lot more detailed than what we already have
(which is absolutely GREAT) but it has many places where a bit of improvement
is needed :-/

There are a few parts that I wanted to mail Brad about asking for extra
clarifications, rewordings, changes in the style and/or content of this.
I just didn't get a chance to read the entire chapter carefully.

Here's what I have so far:

: -       encryption.  FreeBSD 4.4 changed <filename>libcrypt.a</filename> to
: +       encryption.  &os;  4.4 changed <filename>libcrypt.a</filename> to

There's an extra space in there which invalidates  .

: -      Kerberos as distributed for FreeBSD.  However, you should refer to the
: +      Kerberos as distributed for &os;  However, you should refer to the

A fullstop has been trimmed here...

: -        during the initial installation of FreeBSD.  This will install
: +        during the initial installation of &os;  This will install

... and here.

: +        <author>
: +          <firstname>Brad</firstname>
: +          <surname>Davis</surname>
: +                        <contrib>Converted and Updated by </contrib>
: +        </author>

Can we write this as:

        <contrib>Converted to SGML and updated by </contrib>

A conversion usually has a target format ;-)

: +      <title>An Introduction</title>
: +      <para>All software firewall applications are based on monitoring
: +        network packet traffic flow to and from your system. The values
: +        of selected packet control fields can be interrogated by
: +        user-written rules to allow or deny packet traffic based on your
: +        security needs.</para>
: +
: +      <para>Selection can be based on source and destination IP address,
: +        the source and destination port number, the type of protocol
: +        used (TCP, UDP, ICMP), or any combination of the above. Firewall
: +        software  applications provide a much, much finer level of
: +        control than that provided by a hardware router. They can be
: +        used to protect a single &os; system or a complete internal
: +        network (LAN) by preventing public Internet traffic from making
: +        arbitrary connections to your internal network. They may also be
: +        used to prevent public Internet entities from spoofing internal
: +        IP addresses and to disable services you do not want accessed
: +        from the public Internet or by internal LAN users.</para>
: +
: +      <para>Finally, firewalls may be used to support NAT (network
: +        address translation), which allows an internal network using
: +        private IP addresses to share a single connection to the public
: +        Internet, or letting commercial users share a range of static
: +        public IP address automatically among the Lan users.</para>

It seems like too much has been squeezed to fit in a single paragraph of
text.  Parts of the first paragraph are explained in the second, along
with what a firewall can or cannot do.  NAT was initially left out but
added later on as a third paragraph.

This would probably look a bit less confusing if written in a slightly
different style:

%       <title>Introduction</title>
%
%       <para>All software-based firewalls provide some way to filter incoming
%         and outgoing traffic that flows through your system.  The firewall
%         uses one or more sets of <quote>rules</quote> to inspect the network
%         packets as they come in or go out of your network connections and
%         either allows the traffic through or blocks it.  The rules of the
%         firewall can inspect one or more characteristics of the packets,
%         including but not limited to: the protocol type, the source or
%         destination host address and the source or destination port.</para>
%
%       <para>Firewalls greatly enhance the security of your network, your
%         applications and services.  They can be used to do one of more of
%         the following things:</para>
%
%       <itemizedlist>
%         <listitem>
%           <para>To protect and insulate the applications, services and
%             machines of your internal network from unwanted traffic coming
%             in from the public Internet.</para>
%         </listitem>
%
%         <listitem>
%           <para>To limit or disable access from hosts of the internal
%             network to services of the public Internet.</para>
%         </listitem>
%
%         <listitem>
%           <para>To support network address translation (NAT), which allows
%             your internal network to use private IP addresses and share a
%             single connection to the public Internet (either with a single
%             IP address or by a shared pool of automatically assigned public
%             addresses).</para>
%         </listitem>
%       <itemizedlist>

In ``Firewall Rule Set Types'' the words ``inclusive'' and ``exclusive''
should probably be quoted the first time they're used (a glossary entry would
be nice too near that first use).

A few whitespace issues still remain, e.g. this:

: +      <para>An exclusive firewall allows all services through except
: +        for those matching a set of rules that block certain services.
: +        </para>

should probably be changed to move the closing </para> in the previous line
(or pull ``services.'' one line further below, if wrapping is an issue).
Extra whitespace like this can probably cause unwanted whitespace in the
output too, if the stylesheets aren't paranoid about trimming EOL-EOP
whitespace (end of line, end of paragraph).

: +      <para>When you use your browser to access a web site there are
: +        many internal functions that happen before your screen fills
: +        with the data from the target web site. Your browser does not
: +        receive one large file containing all the data and display
: +        format instructions at one time. Each internal function accesses
: +        the public Internet in multiple send/receive cycles of packets
: +        of information. When all the packets containing the data finally
: +        arrive, the data contained in the packets is combined together
: +        to fill your screen. Each service has its own port number. The
: +        port number 80 is for web page services. So you can code your
: +        firewall to only allow web page session start requests
: +        originating from your LAN to pass through the firewall out to
: +        the public Internet.</para>

What is a ``service''?  It sort of jumps out of this paragraph to the unwary
reader without any apparent relation to the web site introduction above it.

: +      <para>&os; has two different firewall software products built
: +        into the base system. They are IPFILTER (i.e. also known as IPF)
: +        and IPFIREWALL (i.e. also known as IPFW). IPFIREWALL has the
: +        built in dummynet traffic shaper facilities for controlling
: +        bandwidth usage.

DUMMYNET is optional and has to explicitly be enabled.  It's also a kernel
option like IPFIREWALL and IPFILTER, so it should probably be capitalized too
if the first two are.

: +      <para>The IPFW sample rule set (found in
: +        <filename>/etc/rc.firewall</filename>) delivered in the basic
: +        install is outdated, complicated and does not use stateful
: +        rules on the interface facing the public Internet. It
: +        exclusively uses legacy stateless rules which only have the
: +        ability to open or close the service ports. The IPFW example
: +        stateful rules sets presented here supercede the
: +        <filename>/etc/firewall.rc</filename> file distributed with the
: +        system.</para>

What are the ``service ports'' referred to here?

: +      <para>The OpenBSD PF user's guide is here:
: +        <ulink url="http://www.openbsd.org/faq/pf/index.html"></ulink>.
: +        </para>

Please trim the unnecessary whitespace here too.

: +      <para>The author of IPFILTER is Darren Reed. IPFILTER is not
: +        operating system dependent. IPFILTER is a open source
: +        application and has been ported to &os;, NetBSD, OpenBSD,
: +        Sun, HP, and Solaris operating systems. IPFILTER is actively
: +        being supported and maintained, with updated versions being
: +        released regularly.</para>

Sun and HP are not operating systems.  Perhaps SunOS and HP/UX was meant to be
added here near Solaris?

: +      <para>The IPFILTER program runs in the kernel and consists of the
: +        firewall and separate NAT facilities. IPFILTER also has
: +        user-land front-end interactive interfaces for controlling the
: +        firewall rules, NAT, packet accounting, and the logging
: +        facility. Program IPF is used to load the firewall rules.
: +        Program IPNAT is used to load the firewall NAT rules. Program
: +        IPFSTAT reports on packet filter statistics and lists active
: +        rules sets. Program IPMON monitors IPFILTER for logged packets.
: +        </para>

The syntax of this paragraph is, well, strange.  "Program FOO does BAR"
doesn't really make sense in English.  Almost every sentence of this has to be
changed to something else:

%       <para>IPFILTER is based on a kernel-side firewall and NAT mechanism
%         that can be controlled and monitored by userland interface programs.
%         The firewall rules can be set or deleted with the &man.ipf.8;
%         utility.  The NAT rules can be set or deleted with the &man.ipnat.8;
%         utility.  The &man.ipfstat.8; utility can print run-time statistics
%         for the kernel parts of IPFILTER.  The &man.ipmon.8; program can log
%         IPFILTER actions to the system log files.</para>

There are a few places where verbatim quotes are used.  These should probably
be replaced with <quote>, <literal> or other SGML elements.

: +        of "the last matching rule wins" and used only stateless type of
: :
: +        using rules that contain the 'quick' option and the stateful
: :
: +        'keep state' option. This is the basic framework for coding an

I haven't had time to review the rest of the text, but since everyone is
anxious to get this committed (which I fully understand), I'll probably wait
until after 5.3-RELEASE to do a sweep of the security chapter and propose a
cleanup diff.

Giorgos