Explain when packets are tesed by the firewall rules and what attributes

of packets can be tested.

PR:		docs/7437

1 files changed, 128 insertions, 23 deletions

diff --git a/sbin/ipfw/ipfw.8 b/sbin/ipfw/ipfw.8
index 7477e32c2223..43194b5cc6af 100644
--- a/sbin/ipfw/ipfw.8
+++ b/sbin/ipfw/ipfw.8
@@ -1,3 +1,6 @@
+.\"
+.\" $Id$
+.\"
 .Dd July 20, 1996
 .Dt IPFW 8 SMM
 .Os FreeBSD
@@ -82,20 +85,96 @@ has been specified, optional
 .Fl D
 and
 .Fl U
-specifcations can follow and will be passed on to the preprocessor.
+specifications can follow and will be passed on to the preprocessor.
 This allows for flexible configuration files (like conditionalizing
 them on the local hostname) and the use of macros to centralize
 frequently required arguments like IP addresses.
 .Pp
+Each packet that has been received or is about to be sent goes through
+the
+.Nm
+rules. In the case of a host acting as a gateway, packets that are
+forwarded by the host are processed by
+.Nm
+twice
+.Po
+once when entering, and once when leaving
+.Pc .
+Each packet can be filtered based on the following information that is
+associated with it:
+.Pp
+.Bl -tag -offset indent -compact -width xxxx
+.It Receive Interface Pq Ar recv
+Interface over which the packet was received
+.It Transmit Interface Pq Ar xmit
+Interface over which the packet would be transmitted
+.It Incoming Pq Ar in
+Packet was just received
+.It Outgoing Pq Ar out
+Packet would be transmitted
+.It Source IP Address
+Sender's IP Address
+.It Destination IP Address
+Target's IP Address
+.It Protocol
+IP protocol, including but not limited to IP
+.Pq Ar ip ,
+UDP
+.Pq Ar udp ,
+TCP
+.Pq Ar tcp ,
+or
+ICMP
+.Pq Ar icmp
+.It Source Port
+Sender's UDP or TCP port
+.It Destination Port
+Target's UDP or TCP port
+.It Connection Setup Flag Pq Ar setup
+This packet is a request to setup a TCP connection
+.It Connection Established Flag Pq Ar established
+This packet is part of an established TCP connection
+.It All TCP Flags Pq Ar tcpflags
+One or more of the TCP flags: close connection
+.Pq Ar fin ,
+open connection
+.Pq Ar syn ,
+reset connection
+.Pq Ar rst ,
+push
+.Pq Ar psh ,
+acknowledgment
+.Pq Ar ack ,
+and
+urgent
+.Pq Ar urg
+.It Fragment Flag Pq Ar frag
+This packet is a fragment of an IP packet
+.It IP Options Pq Ar ipoptions
+One or more of the IP options: strict source route
+.Pq Ar ssrr ,
+loose source route
+.Pq Ar lsrr ,
+record route
+.Pq Ar rr ,
+and timestamp
+.Pq Ar ts 
+.El
+.Pp
+Note that may be dangerous to filter on the source IP address or
+source TCP/UDP port because either or both could easily be spoofed.
+.Pp
 The
 .Nm
-code works by going through the rule-list for each packet,
+code works by going through the rule-list for each packet
 until a match is found.
 All rules have two associated counters, a packet count and
 a byte count.
 These counters are updated when a packet matches the rule.
 .Pp
-The rules are ordered by a ``line-number'' from 1 to 65534 that is used
+The rules are ordered by a 
+.Dq line-number
+from 1 to 65534 that is used
 to order and delete rules. Rules are tried in increasing order, and the
 first rule that matches a packet applies.
 Multiple rules may share the same number and apply in
@@ -111,14 +190,17 @@ if any.
 .Pp
 The list command prints out the current rule set.
 .Pp
-The show command is equivalent to `ipfw -a list'.
+The show command is equivalent to 
+.Sq ipfw -a list .
 .Pp
 The zero operation zeroes the counters associated with rule number
 .Ar number .
 .Pp
 The flush operation removes all rules.
 .Pp
-Any command beginning with a '#', or being all blank, is ignored.
+Any command beginning with a 
+.Sq # ,
+or being all blank, is ignored.
 .Pp
 One rule is always present:
 .Bd -literal -offset center
@@ -143,22 +225,32 @@ system as an on-demand denial-of-service filter that is normally wide open.
 The following options are available:
 .Bl -tag -width flag
 .It Fl a
-While listing, show counter values.  See also ``show'' command.
+While listing, show counter values.  See also 
+.Dq show
+command.
 .It Fl f
 Don't ask for confirmation for commands that can cause problems if misused
-(ie; flush).
+(i.e. flush).
 .Ar Note ,
 if there is no tty associated with the process, this is implied.
 .It Fl q
 While adding, zeroing or flushing, be quiet about actions (implies '-f'). 
-This is useful for adjusting rules by executing multiple ipfw commands in a
-script (e.g. sh /etc/rc.firewall), or by processing a file of many ipfw rules,
+This is useful for adjusting rules by executing multiple
+.Nm
+commands in a script
+.Po
+e.g.,
+.Sq sh /etc/rc.firewall
+.Pc ,
+or by processing a file of many
+.Nm 
+rules,
 across a remote login session.  If a flush is performed in normal
 (verbose) mode (with the default kernel configuration), it prints a message.
 Because all rules are flushed, the
-message cannot be delivered to the login session, the login session is
-closed and the remainder of the ruleset is not processed.  Access to the
-console is required to recover.
+message cannot be delivered to the login session.  This causes the
+remote login session to be closed and the remainder of the ruleset is
+not processed.  Access to the console is required to recover.
 .It Fl t
 While listing, show last match timestamp.
 .It Fl N
@@ -211,7 +303,9 @@ or
 The search terminates.
 .It Ar reset
 TCP packets only. Discard packets that match this rule,
-and try to send a TCP reset (RST) notice.
+and try to send a TCP reset
+.Pq RST
+notice.
 The search terminates.
 .It Ar count
 Update counters for all packets that match rule.
@@ -268,7 +362,8 @@ rule, all but the last are ignored.
 .Pp
 If the kernel was compiled with
 .Dv IPFIREWALL_VERBOSE ,
-then when a packet matches a rule with the ``log''
+then when a packet matches a rule with the
+.Ar log
 keyword a message will be printed on the console.
 If the kernel was compiled with the
 .Dv IPFIREWALL_VERBOSE_LIMIT
@@ -324,7 +419,8 @@ In this case all ip numbers from 1.2.0.0 to 1.2.15.255 will match.
 .El
 .Pp
 The sense of the match can be inverted by preceding an address with the
-``not'' modifier, causing all other addresses to be matched instead. This
+.Dq not
+modifier, causing all other addresses to be matched instead. This
 does not affect the selection of port numbers.
 .Pp
 With the TCP and UDP protocols, optional
@@ -444,7 +540,8 @@ The supported IP options are:
 .Ar ts 
 (timestamp).
 The absence of a particular option may be denoted
-with a ``!''.
+with a
+.Dq ! .
 .It established
 Matches packets that have the RST or ACK bits set.
 TCP packets only.
@@ -464,7 +561,8 @@ The supported TCP flags are:
 and
 .Ar urg .
 The absence of a particular flag may be denoted
-with a ``!''.
+with a
+.Dq ! .
 A rule which contains a
 .Ar tcpflags
 specification can never match a fragmented packet which has
@@ -513,9 +611,12 @@ ipfw flush
 in similar surroundings is also a bad idea.
 .Pp
 The IP filter list may not be modified if the system security level
-is set to 3 or higher (see
+is set to 3 or higher
+.Po
+see
 .Xr init 8
-for information on system security levels).
+for information on system security levels
+.Pc .
 .Sh PACKET DIVERSION
 A divert socket bound to the specified port will receive all packets diverted
 to that port; see
@@ -534,9 +635,11 @@ from being forwarded by the host:
 This one disallows any connection from the entire crackers network to
 my host:
 .Pp
-.Dl ipfw addf deny all from 123.45.67.0/24 to my.host.org
+.Dl ipfw add deny all from 123.45.67.0/24 to my.host.org
 .Pp
-Here is a good usage of the list command to see accounting records
+Here is a good usage of the
+.Ar list
+command to see accounting records
 and timestamp information:
 .Pp
 .Dl ipfw -at l
@@ -560,7 +663,7 @@ This rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000:
 .Xr kldload 8 ,
 .Xr reboot 8 ,
 .Xr sysctl 8 ,
-.Xr syslogd 8
+.Xr syslogd 8 .
 .Sh BUGS
 .Pp
 .Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
@@ -582,7 +685,9 @@ are not.
 .Pp
 Port aliases containing dashes cannot be first in a list.
 .Pp
-The ``tee'' action is unimplemented.
+The
+.Dq tee
+action is unimplemented.
 .Sh AUTHORS
 .An Ugen J. S. Antsilevich ,
 .An Poul-Henning Kamp ,