working on faq/pf

(Please carbon-copy me on replies.)

1) I have at least 35 changes covering missing commas, missing space, 
fixing mispellings and various other minor improvements to the 
faq/pf/*html files. (I have sent most of these to OpenBSD committer who 
works on this.) It would be easier to have some (or all) of these 
committed so I don't have to work on keeping multiple copies of the faq/pf 
tree around for submitting future diffs.

And some other stuff to do:

2) I noticed that some topics are duplicated (including mispellings). I'd 
like to consolidate some of the redundant information, in particular the 
defining of the src_addr and dst_addr and port ranges in 
faq/pf/filter.html and faq/pf/nat.html. Anyone working on that already?

3) Explain backslash means line continuation (is obvious, but # mark is 
obvious too and that is documented multiple times).

4) Create four graphical figures for the few text-based diagrams. Not 
important for text based browsers though.

5) Be consistent with "Note". Some are bold, some are all caps (NOTE), and 
some have colon (Note:).

6) Be consistent with command line examples; some have a hash mark to 
show it is a shell and some don't. (Using a # seems fine.)

7) Be consistent when referencing PF; the usage is now mixed: "pf", 
"pf(4)" and "PF". I suggest using "PF" as appropriate and only pf(4) if 
needing to talk about technical (or kernel) specifics.

8) On first reference of some RFCs, also give the RFC title.

9) Maybe get rid of "it's had" and use "it has had" for better 
readability.

10) Include URLs to outside docs in actual text content to help those who 
may have a PDF that doesn't follow links or for hard-copies. (Of course, 
they could always read the printout and then go back to the pf docs and 
then find the link and click on it.)

11) Maybe show how to flush rules or clear statistics. (-F is only 
described in reference to a specific anchor.)

12) "self" is mention in "Specifying Addresses" but is never really 
described.

13) Maybe include examples for various port ranges (and don't duplicate 
this).

14) In "Checking NAT Status", also describe the MULTIPLE:SINGLE (since not 
I don't think documented in man pages and if it is point to it). It 
doesn't appear to be default TCP States (but is added in 
pf_print_state.c). Where documented with pf source? (I saw it documented 
somewhere, but can't find now.)

15) Also with same section, say that it is source:destination.

16) Rewrite the long sentence in faq/pf/rdr.html "Also be aware that since 
translation occurs ..." (split into a couple sentences or reword).

17) The "Keyword Ordering" example in faq/pf/shortcuts.html shows use of 
"label" but that is not documented elsewhere in the faq/pf.

18) Maybe explain or identify between different uses of the term 
"options" (some are "set" options and others are options for different 
features). I may have missed this in the faq/pf and maybe I am mistaken 
about this, but someone may try to do "set ..." with some option that is 
not available. (Clarification would be appreciated.)

19) In the "Configuring Queueing" section in faq/pf/queueing.html, quickly 
(one sentence) mention what the original implementation of ALTQ is and 
where it came from. Maybe the first sentence can be changed to:

 "Since OpenBSD 3.0, the Alternate Queueing (ALTQ) framework from the KAME
 Project has been a part of the base system. It provides flexible traffic 
 scheduling and bandwidth rate limiting."

This also removed redundant "Alternate Queueing queueing 
implementation".

20) Also in the "Configuring Queueing" section, where it describes each 
syntax setting, maybe repeat the keywords too for some; for example:

Change:
<li><i>interface</i>
To:
<li><tt>on <i>interface</i></tt>

And change:
<li><i>bw</i>
to:
<li><tt>bandwidth <i>bw</i></tt>

and for a few others too.

21) In the faq/pf/perf.html, maybe point to benchmarks anyways, such as 
Hartmeier's old "Design and Performance of the OpenBSD Stateful Packet 
Filter" which provides a performance evaluation.

22) In the "FTP Client Behind the Firewall" section in faq/pf/ftp.html, 
double-check the reference to "/usr/libexec/ftp-proxy". It appears that on 
now in OpenBSD 3.8 this is in /usr/sbin instead.

Should this mention the differences between old proxy and new (aka pftpx)?

23) The "More Information on FTP" section only has one link. Maybe just 
link to it above (previous section) for this one sentence and remove this 
"More Information on FTP" section. Unless other information is to be 
added?

24) Are there in basic features in PF that have been missed in the faq/pf?

25) Are there other keywords shown in examples, but never described in the 
same document?

I can provide more patches for the above.

I see this www list has very little discussion (and more spam than 
content).

I'd appreciate any feedback on this.

Please CC me on replies.

 Jeremy C. Reed

 	  	 	 BSD News, BSD tutorials, BSD links
	  	 	 http://www.bsdnewsletter.com/