Date: Sun, 27 Oct 2002 14:42:10 -0500 (EST) From: Chris Pepper <pepper@rockefeller.edu> To: FreeBSD-gnats-submit@FreeBSD.org Cc: Luigi Rizzo <luigi@FreeBSD.org> Subject: docs/44541: Many fixes for /usr/share/man/man8/ipfw.8.gz Message-ID: <20021027194210.02D8EAC58@www.reppep.com>
next in thread | raw e-mail | index | archive | help
>Number: 44541
>Category: docs
>Synopsis: Many fixes for /usr/share/man/man8/ipfw.8.gz
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Oct 27 11:50:04 PST 2002
>Closed-Date:
>Last-Modified:
>Originator: Chris Pepper
>Release: FreeBSD 4.7-STABLE i386
>Organization:
>Environment:
System: FreeBSD www.reppep.com 4.7-STABLE FreeBSD 4.7-STABLE #6: Sun Oct 20 18:15:59 EDT 2002 root@www.reppep.com:/usr/obj/usr/src/sys/GENERIC i386
>Description:
There are several problems in the ipfw man page with straightforward fixes:
Instructions for getting IPFW2 in 4-STABLE were unclear -- reworded.
s/Section/section/
s/invokation/invocation/
Various spelling & grammar fixes.
Additionally, there are several problems which I am not certain of the fixes for:
{ MAC | mac } dst-mac src-mac
Match packets with a given dst-mac and src-mac addresses, speci-
fied as the any keyword (matching any MAC address), or six groups
of hex digits separated by commas, and optionally followed by a
mask indicating how many bits are significant, as in
MAC 10:20:30:40:50:60/33 any
Note that the order of MAC addresses (destination first, source
second) is the same as on the wire, but the opposite of the one
used for IP addresses.
Text says commas, example uses colons -- which is right, or are both valid?
By default, rules are put in set 0, unless you use the set N attribute
when entering a new rule. Sets can be individually and atomically
enabled or disabled, so this mechanism permits an easy way to store mul-
tiple configurations of the firewall and quickly (and atomically) switch
between them. The command to enable/disable sets is
ipfw set disable number ... [enable number ...]
where multiple enable or disable sections can be specified. Command exe-
cution is atomic on all the sets specified in the command. By default,
all sets are enabled.
This implies it is impossible to enable rules without disabling at least one rule, which doesn't appear to be true.
o dynamic rules created from a rule before it had been disabled will
still be active until they expire. In order to delete dynamic rules
you have to explicitly delete the parent rule which generated them;
The set number of rules can be changed with the command
I believe there should be a period instead of semicolon at the end of the bullet item, and a blank line before the last line.
SYSCTL VARIABLES
A set of sysctl(8) variables controls the behaviour of the firewall and
associated modules ( dummynet, bridge ). These are shown below together
with their default value (but always check with the sysctl(8) command
what value is actually in use) and meaning:
I don't have net.inet.ip.dummynet.* or net.inet.ip.firewall.* on my system. Are they all IPFW2-only? If so, this should be mentioned under IPFW2 ENHANCEMENTS.
Additionally, the following options are not supported in
.Nm ipfw1
(RELENG_4)
rules:
.Pp
.Cm ipid, iplen, ipprecedence, iptos, ipttl,
.Cm ipversion, .Cm tcpack, tcpseq, tcpwin .
Should the third ".Cm" simply be removed, or is there something more to it?
>How-To-Repeat:
man ipfw
>Fix:
Suggested patch follows for first set of problems above.
The second set will have to be fixed by someone with a better understanding of IPFW than myself.
--- ipfw.8.patch begins here ---
--- ipfw.8.system Sun Oct 20 23:30:25 2002
+++ ipfw.8 Sun Oct 27 14:20:37 2002
@@ -89,26 +89,25 @@
.Fx
STABLE still uses
.Nm ipfw1
-unless the kernel is compiled with
-.Cm options IPFW2 ,
-and
+unless
.Nm /sbin/ipfw
and
.Nm /usr/lib/libalias
are recompiled with
.Cm -DIPFW2
-and reinstalled (the same effect can be achieved by adding
+and reinstalled (this can be achieved by adding
.Cm IPFW2=TRUE
to
.Nm /etc/make.conf
-before a buildworld).
+before a buildworld) and the kernel is recompiled with
+.Cm options IPFW2 .
.Pp
See the
.Sx IPFW2 ENHANCEMENTS
-Section for a list of features which are not present in
+section for a list of features which are not present in
.Nm ipfw1 .
-This list can also be useful to revise your rules and
-write them more efficiently.
+This list can also be provide hints for revising your rules and
+writing them more efficiently.
.Pp
An
.Nm
@@ -119,7 +118,7 @@
numbered from 1 to 65535.
Packets are passed to
.Nm
-in a number of different places in the protocol stack
+from a number of different places in the protocol stack
(depending on the source and destination of the packet,
it is possible that
.Nm
@@ -171,7 +170,7 @@
.Sx STATEFUL FIREWALL
and
.Sx EXAMPLES
-Sections below for more information on the stateful behaviour of
+sections below for more information on the stateful behaviour of
.Nm .
.Pp
All rules (including dynamic ones) have a few associated counters:
@@ -205,9 +204,9 @@
.Nm
commands to atomically manipulate sets, such as enable,
disable, swap sets, move all rules in a set to another
-one, delete all rules in a set. These can be useful to
+one, and delete all rules in a set. These can be useful to
install temporary configurations, or to test them.
-See Section
+See section
.Sx SETS OF RULES
for more information on
.Em sets .
@@ -253,7 +252,7 @@
.Ql sh\ /etc/rc.firewall ) ,
or by processing a file of many
.Nm
-rules,
+rules
across a remote login session.
If a
.Cm flush
@@ -261,7 +260,7 @@
configuration), it prints a message.
Because all rules are flushed, the message might not be delivered
to the login session, causing the remote login session to be closed
-and the remainder of the ruleset is not processed.
+and the remainder of the ruleset to not be processed.
Access to the console would then be required to recover.
.It Fl S
While listing rules, show the
@@ -271,7 +270,7 @@
listed.
.It Fl s Op Ar field
While listing pipes, sort according to one of the four
-counters (total and current packets or bytes).
+counters (total and current, packets or bytes).
.It Fl t
While listing, show last match timestamp.
.El
@@ -325,7 +324,7 @@
.Cm queue
commands are used to configure the traffic shaper, as shown in the
.Sx TRAFFIC SHAPER CONFIGURATION
-Section below.
+section below.
.Sh PACKET FLOW
.Nm
can be invoked from multiple places in the protocol stack,
@@ -371,7 +370,7 @@
.Nm
is invoked, or the source of the packet.
If a rule contains some match patterns or actions which are not valid
-for the place of invokation (e.g. trying
+for the place of invocation (e.g. trying
to match a MAC header when
.Nm
is called from
@@ -381,7 +380,7 @@
operator in front of such patterns will cause the pattern to
.Em always
match on those packets, which might cause undesired results.
-It is thus responsibility of
+It is thus the responsibility of
the programmer, if necessary, to write a suitable ruleset to
differentiate among the possible places.
.Cm skipto
@@ -423,7 +422,7 @@
TCP, UDP, ICMP, etc.
.It Source and dest. addresses and ports
.It Direction
-See Section
+See section
.Sx PACKET FLOW
.It Transmit and receive interface
By name or address
@@ -440,7 +439,7 @@
.It ICMP types
for ICMP packets
.It User/group ID
-When the packet can be associate to a local socket.
+When the packet can be associated with a local socket.
.El
.Pp
Note that some of the above information, e.g. source MAC or IP addresses and
@@ -467,10 +466,10 @@
.Ar net.inet.ip.fw.autoinc_step
which defaults to 100.
If this is not possible (e.g. because we would go beyond the
-maximum allowed rule number), the same number of the last
+maximum allowed rule number), the number of the last
non-default value is used instead.
.It Cm set Ar set_number
-Each rule is associated to a
+Each rule is associated with a
.Ar set_number
in the range 0..31, with the latter reserved for the
.Em default
@@ -504,7 +503,7 @@
(which is the default when the kernel is compiled with
.Dv IPFIREWALL_VERBOSE
) and the number of packets logged so far for that
-particular rule does not exceed ther
+particular rule does not exceed the
.Cm logamount
parameter.
If no
@@ -516,7 +515,7 @@
.Pp
Once the limit is reached, logging can be re-enabled by
clearing the logging counter
-or the packet counter for that entry, see the
+or the packet counter for that entry; see the
.Cm resetlog
command.
.Pp
@@ -558,7 +557,7 @@
.It Cm fwd | forward Ar ipaddr Ns Op , Ns Ar port
Change the next-hop on matching packets to
.Ar ipaddr ,
-which can be an IP address in dotted quad or a host name.
+which can be an IP address in dotted quad format or a host name.
The search terminates if this rule matches.
.Pp
If
@@ -600,7 +599,7 @@
(for bandwidth limitation, delay, etc.).
See the
.Sx TRAFFIC SHAPER CONFIGURATION
-Section for further information.
+section for further information.
The search terminates; however, on exit from the pipe and if
the
.Xr sysctl 8
@@ -633,7 +632,7 @@
socket bound to port
.Ar port .
The search terminates and the original packet is accepted
-(but see Section
+(but see section
.Sx BUGS
below).
.It Cm unreach Ar code
@@ -798,7 +797,7 @@
can be used to escape the dash
.Pq Ql -
character in a service name (from a shell, the backslash must be
-typed twice to avoid that the shell itself uses it as an escape
+typed twice to avoid the shell itself interpreting it as an escape
character).
.Pp
.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
@@ -946,7 +945,7 @@
.Ar ver .
.It Cm keep-state
Upon a match, the firewall will create a dynamic rule, whose
-default behaviour is to matching bidirectional traffic between
+default behaviour is to match bidirectional traffic between
source and destination IP/port using the same protocol.
The rule has a limited lifetime (controlled by a set of
.Xr sysctl 8
@@ -991,14 +990,14 @@
(i.e. one or more comma-separated single values or ranges).
You can use symbolic names for known values such as
.Em vlan , ipv4, ipv6 .
-Values can be enter as decimal or hexadecimal (if prefixed by 0x),
+Values can be entered as decimal or hexadecimal (if prefixed by 0x),
and they are always printed as hexadecimal (unless the
.Cm -N
option is used, in which case symbolic resolution will be attempted).
.It Cm proto Ar protocol
Matches packets with the corresponding IPv4 protocol.
.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any
-Matches packets received, transmitted or be going through,
+Matches packets received, transmitted or going through,
respectively, the interface specified by exact name
.Ns No ( Ar ifX Ns No ),
by device name
@@ -1137,7 +1136,7 @@
Command execution is atomic on all the sets specified in the command.
By default, all sets are enabled.
.Pp
-When you disable a set, its rules behave as if they were not existing
+When you disable a set, its rules behave as if they do not exist
in the firewall configuration, with only one exception:
.Bl -bullet
.It
@@ -1160,7 +1159,7 @@
.Pp
See the
.Sx EXAMPLES
-Section on some possible uses of sets of rules.
+section on some possible uses of sets of rules.
.Sh STATEFUL FIREWALL
Stateful operation is a way for the firewall to dynamically
create rules for specific flows when packets that
@@ -1220,14 +1219,14 @@
of the flow and the setting of some
.Cm sysctl
variables.
-See Section
+See section
.Sx SYSCTL VARIABLES
for more details.
For TCP sessions, dynamic rules can be instructed to periodically
send keepalive packets to refresh the state of the rule when it is
about to expire.
.Pp
-See Section
+See section
.Sx EXAMPLES
for more examples on how to use dynamic rules.
.Sh TRAFFIC SHAPER CONFIGURATION
@@ -1283,7 +1282,7 @@
.Sm on
.Pp
A value of 0 (default) means unlimited bandwidth.
-The unit must follow immediately the number, as in
+The unit must immediately follow the number, as in
.Pp
.Dl "ipfw pipe 1 config bw 300Kbit/s"
.Pp
@@ -1607,12 +1606,12 @@
Default is no.
.El
.Sh IPFW2 ENHANCEMENTS
-This Section lists the features that have been introduced in
+This section lists the features that have been introduced in
.Nm ipfw2
-and were not present in
+which were not present in
.Nm ipfw1 .
We list them in order of the potential impact that they can
-have in writing your rulesets.
+have on writing rulesets.
You might want to consider using these features in order to
write your rulesets in a more efficient way.
.Bl -tag -width indent
@@ -1633,7 +1632,7 @@
.Pp
The
.Cm layer2
-options might seem redundant, but it is necessary -- packets
+option might seem redundant, but it is necessary -- packets
passed to the firewall from layer3 will not have a MAC header,
so the
.Cm mac-type ip
@@ -1697,7 +1696,7 @@
does not implement sets of rules.
.It MAC header filtering and Layer-2 firewalling.
.Nm ipfw1
-does not implement filtering on MAC header fields, nor it is
+does not implement filtering on MAC header fields, nor is it
invoked on packets from
.Cm ether_demux()
and
@@ -1727,7 +1726,7 @@
.Sh EXAMPLES
There are far too many possible uses of
.Nm
-so this Section will only give a small set of examples.
+so this section will only give a small set of examples.
.Pp
.Ss BASIC PACKET FILTERING
This command adds an entry which denies all tcp packets from
@@ -1738,7 +1737,7 @@
.Pp
.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
.Pp
-This one disallows any connection from the entire crackers
+This one disallows any connection from the entire cracker's
network to my host:
.Pp
.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
@@ -1796,7 +1795,7 @@
rule.
A
.Cm check-state
-rule should be usually placed near the beginning of the
+rule should usually be placed near the beginning of the
ruleset to minimize the amount of work scanning the ruleset.
Your mileage may vary.
.Pp
@@ -1869,7 +1868,7 @@
.Nm
rules are checked both on incoming and outgoing packets.
.Pp
-Should we like to simulate a bidirectional link with bandwidth
+Should we want to simulate a bidirectional link with bandwidth
limitations, the correct way is the following:
.Pp
.Dl "ipfw add pipe 1 ip from any to any out"
@@ -1878,7 +1877,7 @@
.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
.Pp
The above can be very useful, e.g. if you want to see how
-your fancy Web page will look for a residential user which
+your fancy Web page will look for a residential user who
is connected only through a slow link.
You should not use only one pipe for both directions, unless
you want to simulate a half-duplex medium (e.g. AppleTalk,
@@ -1886,7 +1885,7 @@
It is not necessary that both pipes have the same configuration,
so we can also simulate asymmetric links.
.Pp
-Should we like to verify network performance with the RED queue
+Should we want to verify network performance with the RED queue
management algorithm:
.Pp
.Dl "ipfw add pipe 1 ip from any to any"
@@ -1894,7 +1893,7 @@
.Pp
Another typical application of the traffic shaper is to
introduce some delay in the communication.
-This can affect a lot applications which do a lot of Remote
+This can signficantly affect applications which do a lot of Remote
Procedure Calls, and where the round-trip-time of the
connection often becomes a limiting factor much more than
bandwidth:
@@ -1995,13 +1994,13 @@
.Sh BUGS
The syntax has grown over the years and sometimes it might be confusing.
Unfortunately, backward compatibility prevents cleaning up mistakes
-done in the definition of the syntax.
+made in the definition of the syntax.
.Pp
.Em !!! WARNING !!!
.Pp
Misconfiguring the firewall can put your computer in an unusable state,
possibly shutting down network services and requiring console access to
-regain control to it.
+regain control of it.
.Pp
Incoming packet fragments diverted by
.Cm divert
--- ipfw.8.patch ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20021027194210.02D8EAC58>