Date: Tue, 31 May 2011 04:44:38 GMT From: Ben Kaduk <kaduk@mit.edu> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/157452: grammar and style nits in ipfw.8 Message-ID: <201105310444.p4V4icx0090899@red.freebsd.org> Resent-Message-ID: <201105310450.p4V4o9Mu028462@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 157452 >Category: docs >Synopsis: grammar and style nits in 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: Tue May 31 04:50:09 UTC 2011 >Closed-Date: >Last-Modified: >Originator: Ben Kaduk >Release: 9-current >Organization: MIT SIPB >Environment: n/a >Description: A recent commit to ipfw.8 caused me to notice a couple of grammar errors; looking at the source also revealed some style bugs as well. I attach two patches, one whitespace-only to start new sentences on new lines, wrap long lines, and remove trailing whitespace. The other has the actual content changes. >How-To-Repeat: man 8 ipfw and look for 'fib'. >Fix: Patch attached with submission follows: --- ipfw.8.orig 2011-05-30 19:37:52.000000000 -0400 +++ ipfw.8.whitespace 2011-05-30 20:05:35.000000000 -0400 @@ -234,7 +234,8 @@ When listing a table (see the .Sx LOOKUP TABLES section below for more information on lookup tables), format values -as IP addresses. By default, values are shown as integers. +as IP addresses. +By default, values are shown as integers. .It Fl n Only check syntax of the command strings, without actually passing them to the kernel. @@ -566,7 +567,8 @@ .Xr bpf 4 attached to the .Li ipfw0 -pseudo interface. There is no overhead if no +pseudo interface. +There is no overhead if no .Xr bpf 4 is attached to the pseudo interface. .Pp @@ -880,23 +882,29 @@ Processing continues at the next rule. It is possible to use the .Cm tablearg -keyword with a setfib. If tablearg value is not within compiled FIB range packet fib is set to 0. +keyword with a setfib. +If tablearg value is not within compiled FIB range packet fib is set to 0. .It Cm reass Queue and reassemble ip fragments. -If the packet is not fragmented, counters are updated and processing continues with the next rule. +If the packet is not fragmented, counters are +updated and processing continues with the next rule. If the packet is the last logical fragment, the packet is reassembled and, if .Va net.inet.ip.fw.one_pass -is set to 0, processing continues with the next rule, else packet is allowed to pass and search terminates. -If the packet is a fragment in the middle, it is consumed and processing stops immediately. +is set to 0, processing continues with the next rule, +else packet is allowed to pass and search terminates. +If the packet is a fragment in the middle, it is +consumed and processing stops immediately. .Pp Fragments handling can be tuned via .Va net.inet.ip.maxfragpackets and .Va net.inet.ip.maxfragsperpacket -which limit, respectively, the maximum number of processable fragments (default: 800) and +which limit, respectively, the maximum number of +processable fragments (default: 800) and the maximum number of fragments per packet (default: 16). .Pp -NOTA BENE: since fragments do not contain port numbers, they should be avoided with the +NOTA BENE: since fragments do not contain port numbers, +they should be avoided with the .Nm reass rule. Alternatively, direction-based (like @@ -1516,7 +1524,8 @@ .It Cm sockarg Matches packets that are associated to a local socket and for which the SO_USER_COOKIE socket option has been set -to a non-zero value. As a side effect, the value of the +to a non-zero value. +As a side effect, the value of the option is made available as .Cm tablearg value, which in turn can be used as @@ -1731,7 +1740,8 @@ When used with the .Cm skipto action, the user should be aware that the code will walk the ruleset -up to a rule equal to, or past, the given number, and should therefore try keep the +up to a rule equal to, or past, the given number, +and should therefore try keep the ruleset compact between the skipto and the target rules. .Sh SETS OF RULES Each rule belongs to one of 32 different @@ -1939,10 +1949,12 @@ for each /24 destination subnet. .Pp The FLOW_MASK, together with the SCHED_MASK, is used to split -packets into flows. As an example, using +packets into flows. +As an example, using ``src-ip 0x000000ff'' together with the previous SCHED_MASK makes a flow for -each individual source address. In turn, flows for each /24 +each individual source address. +In turn, flows for each /24 subnet will be sent to the same scheduler instance. .Pp The above diagram holds even for the @@ -2065,7 +2077,8 @@ the use of the channel, MAC level retransmissions and so on. From our point of view, the channel is effectively unavailable for this extra time, which is constant or variable depending -on the link type. Additionally, packets may be dropped after this +on the link type. +Additionally, packets may be dropped after this time (e.g. on a wireless link after too many retransmissions). We can model the additional delay with an empirical curve that represents its distribution. @@ -2166,7 +2179,8 @@ .It Cm wf2qp implements the WF2Q+ algorithm, which is a Weighted Fair Queueing algorithm which permits flows to share bandwidth according to -their weights. Note that weights are not priorities; even a flow +their weights. +Note that weights are not priorities; even a flow with a minuscule weight will never starve. WF2Q+ has O(log N) per-packet processing cost, where N is the number of flows, and is the default algorithm used by previous versions @@ -2515,7 +2529,7 @@ Defines the maximum number of chunks in an SCTP packet that will be parsed for a packet that matches an existing association. This value is enforced to be greater or equal than -.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . +.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . A high value is a DoS risk yet setting too low a value may result in important control chunks in the packet not being located and parsed. @@ -2595,7 +2609,8 @@ As for other similar sysctl variables, larger values pose a DoS risk. .It Va net.inet.ip.alias.sctp.log_level: No 0 Level of detail in the system log messages (0 \- minimal, 1 \- event, -2 \- info, 3 \- detail, 4 \- debug, 5 \- max debug). May be a good +2 \- info, 3 \- detail, 4 \- debug, 5 \- max debug). +May be a good option in high loss environments. .It Va net.inet.ip.alias.sctp.shutdown_time: No 15 Timeout value while waiting for SHUTDOWN-COMPLETE. @@ -2614,7 +2629,8 @@ .El .Pp This variable is fully dynamic, the new value will be adopted for all newly -arriving associations, existing associations are treated as they were previously. +arriving associations, existing associations +are treated as they were previously. Global tracking will decrease the number of collisions within the .Nm nat at a cost @@ -2622,7 +2638,7 @@ .Nm nat state problems in complex networks with multiple -.Nm nats . +.Nm nats . We recommend not tracking global IP addresses, this will still result in a fully functional .Nm nat . @@ -3152,8 +3168,8 @@ traffic shaper supported by Akamba Corp. .Pp The ipfw core (ipfw2) has been completely redesigned and -reimplemented by Luigi Rizzo in summer 2002. Further -actions and +reimplemented by Luigi Rizzo in summer 2002. +Further actions and options have been added by various developer over the years. .Pp .An -nosplit >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201105310444.p4V4icx0090899>