Date: Sun, 7 Jul 2002 15:21:05 -0400 (EDT) From: Chris Pepper <pepper@rockefeller.edu> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/40311: Typos and language adjustments to ipfw.8 Message-ID: <20020707192105.078AEA944@guest.reppep.com>
next in thread | raw e-mail | index | archive | help
>Number: 40311
>Category: docs
>Synopsis: Typos and language adjustments to ipfw.8
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Jul 07 12:30:01 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator: Chris Pepper
>Release: FreeBSD 4.6-STABLE i386
>Organization:
>Environment:
System: FreeBSD guest.reppep.com 4.6-STABLE FreeBSD 4.6-STABLE #3: Sun Jul 7 02:08:43 EDT 2002 root@guest.reppep.com:/usr/obj/usr/src/sys/GENERIC i386
>Description:
Various punctuation and grammer enhancements for /usr/share/man/man8/ipfw.8.
There are also a few questions/issues I wasn't sure how to answer or fix:
limit {src-addr | src-port | dst-addr | dst-port} N
The firewall will only allow N connections with the same
set of parameters as specified in the rule. One or more
of source and destination addresses and ports can be
specified.
Should the pipes in the example be changed to something else, to reflect that more than one option is permitted?
net.inet.ip.fw.dyn_short_lifetime: 30
These variables control the lifetime, in seconds, of dynamic
rules. Upon the initial SYN exchange the lifetime is kept short,
then increased after both SYN have been seen, then decreased
again during the final FIN exchange or when a RST
EXAMPLES
The sentence ending with RST is truncated.
>How-To-Repeat:
man ipfw
>Fix:
Apply this patch.
--- ipfw.8.diff begins here ---
--- ipfw.8 Sun Jul 7 00:44:04 2002
+++ ipfw.8.fixed Sun Jul 7 14:55:28 2002
@@ -69,7 +69,7 @@
Depending on the action and certain system settings, packets
can be reinjected into the firewall at the rule after the
matching one for further processing.
-All rules apply to all interfaces, so it is responsibility
+All rules are checked for all interfaces, so it is the responsibility
of the system administrator to write the ruleset in such a
way as to minimize the number of checks.
.Pp
@@ -119,9 +119,9 @@
.Cm add
command; deleted individually with the
.Cm delete
-command, and globally with the
+command and globally with the
.Cm flush
-command; displayed, optionally with the content of the
+command; and displayed, optionally with the content of the
counters, using the
.Cm show
and
@@ -186,7 +186,7 @@
Try to resolve addresses and service names in output.
.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 and bytes).
.El
.Pp
To ease configuration, rules can be put into a file which is
@@ -203,7 +203,7 @@
.Pp
Optionally, a preprocessor can be specified using
.Fl p Ar preproc
-where
+which
.Ar pathname
is to be piped through.
Useful preprocessors include
@@ -357,7 +357,7 @@
.It Cm fwd 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.
If
.Ar ipaddr
is not a directly-reachable address, the route as found in
@@ -470,7 +470,7 @@
.Pa /etc/protocols ) .
The
.Cm ip
-or
+and
.Cm all
keywords mean any protocol will match.
.It Ar src No and Ar dst :
@@ -522,7 +522,7 @@
.Pp
The
.Ql \&:
-notation specifies a port and a mask, a match is declared if
+notation specifies a port and a mask; a match is declared if
the port number in the packet matches the one in the rule,
limited to the bits which are set in the mask.
.Pp
@@ -618,8 +618,8 @@
.Bl -tag -width indent
.It Cm keep-state
Upon a match, the firewall will create a dynamic rule, whose
-default behaviour is to matching bidirectional traffic between
-source and destination IP/port using the same protocol.
+default behaviour is to match bidirectional traffic between
+the source and destination IP/port using the same protocol.
The rule has a limited lifetime (controlled by a set of
.Xr sysctl 8
variables), and the lifetime is refreshed every time a matching
@@ -760,13 +760,13 @@
.Ar user .
A
.Ar user
-may be matched by name or identification number.
+may be specified by name or UID.
.It Cm gid Ar group
Match all TCP or UDP packets sent by or received for a
.Ar group .
A
.Ar group
-may be matched by name or identification number.
+may be specified by name or GID.
.El
.El
.Sh TRAFFIC SHAPER CONFIGURATION
@@ -852,7 +852,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 queue 50KBytes"
.Pp
@@ -885,7 +885,7 @@
queueing delay.
E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
or 20s of queue on a 30Kbit/s pipe.
-Even worse effect can result if you get packets from an
+Even worse effects can result if you get packets from an
interface with a much larger MTU, e.g. the loopback interface
with its 16KB packets.
.It Cm plr Ar packet-loss-rate
@@ -893,12 +893,12 @@
Argument
.Ar packet-loss-rate
is a floating-point number between 0 and 1, with 0 meaning no
-loss, 1 meaning 100% loss.
-The loss rate is internally represented on 31 bits.
+loss and 1 meaning 100% loss.
+The loss rate is internally represented in 31 bits.
.It Cm mask Ar mask-specifier
The
.Xr dummynet 4
-lets you to create per-flow queues.
+lets you create per-flow queues.
A flow identifier is constructed by masking the IP addresses,
ports and protocol types as specified in the pipe configuration.
Packets with the same identifier after masking fall into the
@@ -924,11 +924,11 @@
.It Cm buckets Ar hash-table-size
Specifies the size of the hash table used for storing the
various queues.
-Default value is 64 controlled by the
+The default value is 64; it can be overridden with the
.Xr sysctl 8
variable
.Em net.inet.ip.dummynet.hash_size ,
-allowed range is 16 to 1024.
+from 16 to 1024.
.It Cm pipe Ar pipe_nr
Connects a queue to the specified pipe.
Multiple queues (usually
@@ -973,7 +973,7 @@
rules:
.Bl -bullet
.It
-Remember that you filter both packets going
+Remember that you filter packets going both
.Cm in
and
.Cm out .
@@ -993,8 +993,8 @@
There are circumstances where fragmented datagrams are unconditionally
dropped.
TCP packets are dropped if they do not contain at least 20 bytes of
-TCP header, UDP packets are dropped if they do not contain a full 8
-byte UDP header, and ICMP packets are dropped if they do not contain
+TCP header; UDP packets are dropped if they do not contain a full 8
+byte UDP header; and ICMP packets are dropped if they do not contain
4 bytes of ICMP header, enough to specify the ICMP type, code, and
checksum.
These packets are simply logged as
@@ -1025,7 +1025,7 @@
ipfw flush
.Ed
.Pp
-in similar surroundings is also a bad idea.
+over the network is also a bad idea.
.It
The
.Nm
@@ -1047,16 +1047,16 @@
A set of
.Xr sysctl 8
variables controls the behaviour of the firewall.
-These are shown below together with their default value
+These are shown below together with their default values
(but always check with the
.Xr sysctl 8
-command what value is actually in use) and meaning:
+command to see what value is actually in use) and meaning:
.Bl -tag -width indent
.It Em net.inet.ip.fw.debug : No 1
Controls debugging messages produced by
.Nm .
.It Em net.inet.ip.fw.one_pass : No 1
-When set, the packet exiting from the
+When set, a packet exiting from the
.Xr dummynet 4
pipe is not passed though the firewall again.
Otherwise, after a pipe action, the packet is
@@ -1066,7 +1066,7 @@
.It Em net.inet.ip.fw.enable : No 1
Enables the firewall.
Setting this variable to 0 lets you run your machine without
-firewall even if compiled in.
+a firewall even if compiled in.
.It Em net.inet.ip.fw.verbose_limit : No 0
Limits the number of messages produced by a verbose firewall.
.It Em net.inet.ip.fw.dyn_buckets : No 256
@@ -1146,7 +1146,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
@@ -1165,7 +1165,7 @@
stateful rules can be subject to denial-of-service attacks
by a SYN-flood which opens a huge number of dynamic rules.
The effects of such attacks can be partially limited by
-acting on a set of
+adjusting the
.Xr sysctl 8
variables which control the operation of the firewall.
.Pp
@@ -1183,12 +1183,12 @@
.Pp
.Dl ipfw show
.Pp
-Next rule diverts all incoming packets from 192.168.2.0/24
+This rule diverts all incoming packets from 192.168.2.0/24
to divert port 5000:
.Pp
.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
.Pp
-The following rules show some of the applications of
+The following rules show some of the applications for
.Nm
and
.Xr dummynet 4
@@ -1199,13 +1199,13 @@
.Pp
.Dl "ipfw add prob 0.05 deny ip from any to any in"
.Pp
-A similar effect can be achieved making use of dummynet pipes:
+A similar effect can be achieved by making use of dummynet pipes:
.Pp
.Dl "ipfw add pipe 10 ip from any to any"
.Dl "ipfw pipe 10 config plr 0.05"
.Pp
We can use pipes to artificially limit bandwidth, e.g. on a
-machine acting as a router, if we want to limit traffic from
+machine acting as a router. If we want to limit traffic from
local clients on 192.168.2.0/24 we do:
.Pp
.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
@@ -1218,7 +1218,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"
@@ -1227,7 +1227,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,
@@ -1235,14 +1235,14 @@
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 desire to verify network performance with the RED queue
management algorithm:
.Pp
.Dl "ipfw add pipe 1 ip from any to any"
.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
.Pp
Another typical application of the traffic shaper is to
-introduce some delay in the communication.
+introduce some delay in communications.
This can affect a lot 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
@@ -1269,8 +1269,7 @@
when
.Nm
tries to match IP packets it will not consider ports, so we
-would not see connections on separate ports as different
-ones.
+would not see connections on separate ports as distinct otherwise.
.Pp
A more sophisticated example is limiting the outbound traffic
on a net with per-host limits, rather than per-network limits:
@@ -1292,7 +1291,7 @@
are invoked.
This means that packets are processed once for connections having
only one endpoint on the local host, twice for connections with
-both endpoints on the local host, or for packet routed by the host
+both endpoints on the local host or routed by the host
(acting as a gateway), and once for packets bridged by the host
(acting as a bridge).
.Sh SEE ALSO
@@ -1315,7 +1314,7 @@
.Pp
.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
.Pp
-This program can put your computer in rather unusable state.
+This program can easily put your computer in an unusable state.
When using it for the first time, work on the console of the
computer, and do
.Em NOT
--- ipfw.8.diff 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?20020707192105.078AEA944>