bin/38078: IPFilter is so poorly documented it can't even pretend to have any sort of documentation

[cube%cubidou.net@localhost]

>Number:         38078
>Category:       bin
>Synopsis:       IPFilter lacks documentation almost completely
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Feb 21 11:55:00 +0000 2008
>Originator:     Quentin Garnier
>Release:        NetBSD 4.0 and later
>Organization:
        NetBSD
>Environment:
                NetBSD 4.0 and later
>Description:
        IPFilter appears to have a much richer syntax for its main
        configuraton file than anyone can assume from reading the
        man page, which already barely stands as correct documentation,
        giving no hints whatsoever for most of the keywords.

        IPFilter is a security product.  It is bad not to document
        security tools properly, because it leads to mistake that are
        potentially dangerous for people's data and systems.

        For instance, did anyone reading this, except maybe Darren Reed,
        knew you could list addresses, ports and interfaces using
        parenthesis?  Did anyone know about the "with frag-body"
        keyword?  I have yet to read the code further to know what that
        one actually does.  The "with oow" seems interesting too,
        considering I am currently fighting an issue of IPFilter
        insisting on dropping some packets because it thinks they are
        out of window.

        I'm sure that when I'm finished reading ipf_y.y I will have
        learned a lot about the syntax of ipf.conf that hardly anybody
        in the NetBSD community knows.

        That's a shame.
>How-To-Repeat:
        Read ipf.conf(5).  Compare to ipf_y.y.  Ouch.
>Fix:
        I was having a dim hope that a newer version of IPFilter would
        have a more complete ipf.5, but well, it appears not to be the
        case.

        Writing the documentation is not very hard, but it does take a
        lot of time, I'm aware of that.  It's a nice little project for
        someone who wants to learn about Yacc _and_ IPFilter _and_ the
        way IPFilter works in the kernel (the latter being because you
        will have to figure out what exactly each keyword does).