From owner-freebsd-doc@FreeBSD.ORG Mon Sep 20 13:31:11 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id BEE7016A4CE for ; Mon, 20 Sep 2004 13:31:11 +0000 (GMT) Received: from rosebud.otenet.gr (rosebud.otenet.gr [195.170.0.26]) by mx1.FreeBSD.org (Postfix) with ESMTP id C690743D5D for ; Mon, 20 Sep 2004 13:31:10 +0000 (GMT) (envelope-from keramida@freebsd.org) Received: from orion.daedalusnetworks.priv (host5.bedc.ondsl.gr [62.103.39.229])i8KDUjAw009638; Mon, 20 Sep 2004 16:30:51 +0300 Received: from orion.daedalusnetworks.priv (orion [127.0.0.1]) i8KDUW9e039209; Mon, 20 Sep 2004 16:30:32 +0300 (EEST) (envelope-from keramida@freebsd.org) Received: (from keramida@localhost)i8KDUPng039208; Mon, 20 Sep 2004 16:30:25 +0300 (EEST) (envelope-from keramida@freebsd.org) Date: Mon, 20 Sep 2004 16:30:25 +0300 From: Giorgos Keramidas To: Ceri Davies , Brad Davis Message-ID: <20040920133025.GB38865@orion.daedalusnetworks.priv> 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> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040920110628.GA2493@submonkey.net> cc: freebsd-doc@freebsd.org Subject: New firewall section (was: Re: HEADS UP: doc/ slush begins) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Sep 2004 13:31:11 -0000 On 2004-09-20 12:06, Ceri Davies 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 libcrypt.a to : + encryption. &os;  4.4 changed libcrypt.a 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. : + : + Brad : + Davis : + Converted and Updated by : + Can we write this as: Converted to SGML and updated by A conversion usually has a target format ;-) : + An Introduction : + 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. : + : + 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. : + : + 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. 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: % Introduction % % 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 rules 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. % % 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: % % % % To protect and insulate the applications, services and % machines of your internal network from unwanted traffic coming % in from the public Internet. % % % % To limit or disable access from hosts of the internal % network to services of the public Internet. % % % % 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). % % 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: : + An exclusive firewall allows all services through except : + for those matching a set of rules that block certain services. : + should probably be changed to move the closing 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). : + 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. 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. : + &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. : + The IPFW sample rule set (found in : + /etc/rc.firewall) 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 : + /etc/firewall.rc file distributed with the : + system. What are the ``service ports'' referred to here? : + The OpenBSD PF user's guide is here: : + . : + Please trim the unnecessary whitespace here too. : + 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. Sun and HP are not operating systems. Perhaps SunOS and HP/UX was meant to be added here near Solaris? : + 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. : + 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: % 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. There are a few places where verbatim quotes are used. These should probably be replaced with , 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