Date: Mon, 20 Sep 2004 16:30:25 +0300 From: Giorgos Keramidas <keramida@freebsd.org> To: Ceri Davies <ceri@submonkey.net>, Brad Davis <so14k@so14k.com> Cc: freebsd-doc@freebsd.org Subject: New firewall section (was: Re: HEADS UP: doc/ slush begins) Message-ID: <20040920133025.GB38865@orion.daedalusnetworks.priv> In-Reply-To: <20040920110628.GA2493@submonkey.net> References: <20040918.161309.35654157.hrs@eos.ocn.ne.jp> <20040919105246.GW1538@submonkey.net> <200409191740.06579.so14k@so14k.com> <200409191905.56649.so14k@so14k.com> <20040920110628.GA2493@submonkey.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2004-09-20 12:06, Ceri Davies <ceri@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040920133025.GB38865>