From pepper@reppep.com Sun Oct 27 11:42:11 2002 Return-Path: Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 47F2037B401; Sun, 27 Oct 2002 11:42:11 -0800 (PST) Received: from www.reppep.com (www.reppep.com [66.92.104.200]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2A03443E42; Sun, 27 Oct 2002 11:42:10 -0800 (PST) (envelope-from pepper@reppep.com) Received: by www.reppep.com (Postfix, from userid 501) id 02D8EAC58; Sun, 27 Oct 2002 14:42:10 -0500 (EST) Message-Id: <20021027194210.02D8EAC58@www.reppep.com> Date: Sun, 27 Oct 2002 14:42:10 -0500 (EST) From: Chris Pepper Reply-To: Chris Pepper To: FreeBSD-gnats-submit@freebsd.org Cc: Luigi Rizzo Subject: Many fixes for /usr/share/man/man8/ipfw.8.gz X-Send-Pr-Version: 3.113 X-GNATS-Notify: >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: closed >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sun Oct 27 11:50:04 PST 2002 >Closed-Date: Mon Nov 18 14:03:08 PST 2002 >Last-Modified: Mon Nov 18 14:03:08 PST 2002 >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: From: Chris Pepper To: swear@attbi.com (Gary W. Swearingen) Cc: FreeBSD-gnats-submit@FreeBSD.org, Luigi Rizzo Subject: Re: docs/44541: Many fixes for /usr/share/man/man8/ipfw.8.gz Date: Sun, 27 Oct 2002 21:34:45 -0500 Gary, I was trying to make the minimal valid changes, but agree that several of the problems merit larger fixes. At the end of this message is a revised patch. At 3:58 PM -0800 2002/10/27, Gary W. Swearingen wrote: > > The set number of rules can be changed with the command > >Should that be "numbers"? I don't know. The sentence is easy to read >wrong too; it'd be better to refer to a "set" instead of a "set number" >in all but a very few places. Both of these are nit-picking. Changed to: The set number of a rule or set can be changed with the command > > .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). > >That could use some work. It's not at all clear what one should use for >"field". Elsewhere it says there are three counters (packets, bytes, >and logs). Just considering the raw text, it should use either both "or" >(referring to "one") or both "and" (referring to "four counters"). The >comma isn't correct, but it's tolerable. How about "(total (or current) >packets (or bytes))". If "field" is supposed to be one of four strings, >then list them verbatim. Someone who knows the actual syntax has to fix this. > > 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 > >Should be "e.g., trying" (with a comma). Comma added here and after "e.g." in several other places. > > @@ -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. > >That problem is in several other places too. An alternative: >+which can be a dotted-quad IP address or a host name. normalized to "dotted quad IP address" in 3 other places. > > .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 > >Doesn't sound right to me. I'd use the first of these: >+type twice to avoid its interpretation as an escape >+type twice to avoid the interpretation of it as an escape >+type twice to avoid the shell's interpretation of it as an escape >+type twice to avoid having the shell interpret it as an escape Changed to: typed twice to avoid having the shell itself interpret it as an escape > > -Values can be enter as decimal or hexadecimal (if prefixed by 0x), >> +Values can be entered as decimal or hexadecimal (if prefixed by 0x), > >Poor English, but clear enough. Better: >+Values can be entered as hexadecimal (if prefixed by 0x) or decimal, Changed to: Values can be entered in decimal format, or hexadecimal format if prefixed by 0x, > > -Matches packets received, transmitted or be going through, >> +Matches packets received, transmitted or going through, > >Is there a -doc convention on this, or is the list comma optional? >+Matches packets received, transmitted, or passing through, No idea what convention is, although personally I think it should be there. > > +When you disable a set, its rules behave as if they do not exist >> in the firewall configuration, with only one exception: > >+While a set is disabled, its rules have no effect, with one exception: Changed to: When a set is disabled, its rules behave as if they do not exist in the firewall configuration, with only one exception: > > -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 . > >Seems redundant. > >+This section lists the features which are in >.Nm ipfw2 >but not >.Nm ipfw1 . > >(Or "but are not in".) Changed to: This section lists new features that have been introduced in .Nm ipfw2 . > > .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: > >Either "the entire cracker network" or "the cracker's entire network". >(Maybe that first one should have "cracker" in italics.) Changed to: This one disallows any connection from the cracker's entire Patch follows. Chris Pepper --- ipfw.8.system Sun Oct 20 23:30:25 2002 +++ ipfw.8 Sun Oct 27 21:32:53 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 @@ -306,7 +305,7 @@ Care should be taken with this in environments where not all file systems are mounted (yet) by the time .Nm -is being run (e.g. when they are mounted over NFS). +is being run (e.g., when they are mounted over NFS). Once .Fl p has been specified, optional @@ -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,10 +439,10 @@ .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 +Note that some of the above information, e.g., source MAC or IP addresses and TCP/UDP ports, could easily be spoofed, so filtering on those fields alone might not guarantee the desired results. .Bl -tag -width indent @@ -466,11 +465,11 @@ non-default rule number by the value of the sysctl variable .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 +If this is not possible (e.g., because we would go beyond the +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 @@ -739,12 +738,12 @@ The address list is evaluated at the time the packet is analysed. .It Ar numeric-ip | hostname -Matches a single IPv4 address, specified as dotted-quad or a hostname. +Matches a single IPv4 address, specified as dotted quad IP address or a hostname. Hostnames are resolved at the time the rule is added to the firewall list. .It Ar addr Ns / Ns Ar masklen Matches all addresses with base .Ar addr -(specified as a dotted quad or a hostname) +(specified as a dotted quad IP address or a hostname) and mask width of .Cm masklen bits. @@ -753,7 +752,7 @@ .It Ar addr Ns / Ns Ar masklen Ns Cm { Ns Ar num,num,... Ns Cm } Matches all addresses with base address .Ar addr -(specified as a dotted quad or a hostname) +(specified as a dotted quad IP address or a hostname) and whose last byte is in the list between braces { } . Note that there must be no spaces between braces, commas and numbers. @@ -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 having the shell itself interpret it as an escape character). .Pp .Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" @@ -834,7 +833,7 @@ .It Cm frag Matches packets that are fragments and not the first fragment of an IP datagram. Note that these packets will not have -the next protocol header (e.g. TCP, UDP) so options that look into +the next protocol header (e.g., TCP or UDP) so options that look into these headers cannot match. .It Cm gid Ar group Matches all TCP or UDP packets sent by or received for a @@ -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 in decimal format, or hexadecimal format 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 a set is disabled, its rules behave as if they do not exist in the firewall configuration, with only one exception: .Bl -bullet .It @@ -1146,7 +1145,7 @@ dynamic rules you have to explicitly delete the parent rule which generated them; .El -The set number of rules can be changed with the command +The set number of a rule or set can be changed with the command .Pp .Nm .Cm set move @@ -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 @@ -1391,7 +1390,7 @@ 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 -interface with a much larger MTU, e.g. the loopback interface +interface with a much larger MTU, e.g., the loopback interface with its 16KB packets. .Pp .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p @@ -1607,12 +1606,10 @@ Default is no. .El .Sh IPFW2 ENHANCEMENTS -This Section lists the features that have been introduced in -.Nm ipfw2 -and were not present in -.Nm ipfw1 . +This section lists new features that have been introduced in +.Nm ipfw2 . 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 +1630,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 +1694,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 +1724,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 +1735,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 cracker's entire network to my host: .Pp .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" @@ -1796,7 +1793,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 @@ -1855,7 +1852,7 @@ .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 +We can use pipes to artificially limit bandwidth, e.g., on a machine acting as a router, if we want to limit traffic from local clients on 192.168.2.0/24 we do: .Pp @@ -1869,7 +1866,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" @@ -1877,16 +1874,16 @@ .Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" .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 +The above can be very useful, e.g., if you want to see how +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, +you want to simulate a half-duplex medium (e.g., AppleTalk, Ethernet, IRDA). 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 +1891,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: @@ -1931,7 +1928,7 @@ .Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Ss SETS OF RULES -To add a set of rules atomically, e.g. set 18: +To add a set of rules atomically, e.g., set 18: .Pp .Dl "ipfw disable set 18" .Dl "ipfw add NN set 18 ... # repeat as needed" @@ -1948,7 +1945,7 @@ .Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18" .Pp Here if everything goes well, you press control-C before the "sleep" -terminates, and your ruleset will be left active. Otherwise, e.g. if +terminates, and your ruleset will be left active. Otherwise, e.g., if you cannot access your box, the ruleset will be disabled after the sleep terminates thus restoring the previous situation. .Sh SEE ALSO @@ -1995,13 +1992,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 State-Changed-From-To: open->closed State-Changed-By: luigi State-Changed-When: Mon Nov 18 14:02:46 PST 2002 State-Changed-Why: most suggestions integrated in a later rewrite of the page. http://www.freebsd.org/cgi/query-pr.cgi?pr=44541 >Unformatted: