new mdoc ipftest(1) man page; kwesterback@home.com

1 files changed, 136 insertions, 114 deletions

diff --git a/usr.sbin/ipftest/ipftest.1 b/usr.sbin/ipftest/ipftest.1
index 52b260de12d..3663c7032d1 100644
--- a/usr.sbin/ipftest/ipftest.1
+++ b/usr.sbin/ipftest/ipftest.1
@@ -1,128 +1,150 @@
-.\"     $OpenBSD: ipftest.1,v 1.7 1999/02/10 22:12:53 deraadt Exp $          
-.TH ipftest 1
-.SH NAME
-ipftest \- test packet filter rules with arbitrary input.
-.SH SYNOPSIS
-.B ipftest
-[
-.B \-vbdPSTEHX
-] [
-.B \-I
-interface
-]
-.B \-r
-<filename>
-[
-.B \-i
-<filename>
-]
-.SH DESCRIPTION
-.PP
-\fBipftest\fP is provided for the purpose of being able to test a set of
-filter rules without having to put them in place, in operation and proceed
-to test their effectiveness.  The hope is that this minimizes disruptions
-in providing a secure IP environment.
-.PP
-\fBipftest\fP will parse any standard ruleset for use with \fBipf\fP
-and apply input, returning output as to the result.  However, \fBipftest\fP
-will return one of three values for packets passed through the filter:
-pass, block or nomatch.  This is intended to give the operator a better
-idea of what is happening with packets passing through their filter
-ruleset.
-.PP
-When used without either of \fB\-S\fP, \fB\-T\fP or \fB\-E\fP,
-\fBipftest\fP uses its own text input format to generate "fake" IP packets.
-The format used is as follows:
-.nf
-		"in"|"out" "on" if ["tcp"|"udp"|"icmp"]
-			srchost[,srcport] dsthost[,destport] [FSRPAU]
-.fi
-.PP
-This allows for a packet going "in" or "out" of an interface (if) to be
-generated, being one of the three main protocols (optionally), and if
-either TCP or UDP, a port parameter is also expected.  If TCP is selected,
-it is possible to (optionally) supply TCP flags at the end.  Some examples
-are:
-.nf
-		# a UDP packet coming in on le0
-		in on le0 udp 10.1.1.1,2210 10.2.1.5,23
-		# an IP packet coming in on le0 from localhost - hmm :)
-		in on le0 localhost 10.4.12.1
-		# a TCP packet going out of le0 with the SYN flag set.
-		out on le0 tcp 10.4.12.1,2245 10.1.1.1,23 S
-.fi
-.SH OPTIONS
-.TP
-.B \-v
+.\"     $OpenBSD: ipftest.1,v 1.8 1999/05/24 23:39:57 aaron Exp $          
+.Dd May 23, 1999
+.Os
+.Dt IPFTEST 1
+.Sh NAME
+.Nm ipftest
+.Nd test packet filter rules with arbitrary input
+.Sh SYNOPSIS
+.Nm ipftest
+.Op Fl vbdPSTEHX
+.Op Fl I Ar interface
+.Fl r
+.Ar filename
+.Op Fl i Ar filename
+.Sh DESCRIPTION
+With
+.Nm
+operators can see the effects of an
+.Nm ipf
+filter ruleset on test packets, rather than having to observe
+the effects of the
+ruleset on live traffic. This can reduce the disruptions experienced
+during the development and refinement of secure IP environments.
+.Pp
+.Nm
+reads test packets from
+.Ar stdin
+or the file specified by the
+.Fl i
+option, applies the ruleset specified by the 
+.Fl r
+option to each, and generates information about the effect of the ruleset on
+each packet to 
+.Ar stdout .
+.Pp
+Captured or handcrafted packets to be tested can be supplied
+in a variety of formats. See the options
+.Fl P , Fl S , 
+.Fl T , Fl H 
+and
+.Fl E 
+for details. In addition the
+.Fl X
+option gives 
+.Nm
+the ability to use its own text description format to generate 
+.Dq fake 
+packets.  The format used is:
+.Bd -ragged 
+in|out on
+.Ar if
+.Op tcp|udp|icmp
+.Ar srchost
+.Op , Ar port 
+.Ar dsthost
+.Op , Ar port
+.Op Fl FSRPAU
+.Ed
+.Pp
+This allows for input or output ICMP, TCP, or UDP packets to be generated for 
+any interface. For TCP or UDP it allows the specification of source and
+destination ports. For TCP it allows the specification of TCP flags. 
+Some examples are:
+.Bd -literal -offset indent
+# a UDP packet coming in on le0
+in on le0 udp 10.1.1.1,2210 10.2.1.5,23
+# an IP packet coming in on le0 from localhost - hmm :)
+in on le0 localhost 10.4.12.1
+# a TCP packet going out of le0 with the SYN flag set.
+out on le0 tcp 10.4.12.1,2245 10.1.1.1,23 S
+.Ed
+.Pp
+The following options are available:
+.Bl -tag -width Fl
+.It Fl v
 Verbose mode.  This provides more information about which parts of rule
-matching the input packet passes and fails.
-.TP
-.B \-d
-Turn on filter rule debugging.  Currently, this only shows you what caused
+matching the packet passes and fails.
+.It Fl d
+Turn on filter rule debugging.  Currently, this only shows what caused
 the rule to not match in the IP header checking (addresses/netmasks, etc).
-.TP
-.B \-b
-Cause the output to be a brief summary (one-word) of the result of passing
-the packet through the filter; either "pass", "block" or "nomatch".
+.It Fl b
+Cause the output to be a one word description of the result of passing
+the packet through the filter: pass, block or nomatch.
 This is used in the regression testing.
-.TP
-.BR \-I \0<interface>
+.It Fl I Ar interface
 Set the interface name (used in rule matching) to be the name supplied.
-This is useful with the \fB\-P, \-S, \-T\fP and \fB\-E\fP options, where it is
+This is useful with the
+.Fl P , Fl S
+and
+.Fl E
+options, where it is
 not otherwise possible to associate a packet with an interface.  Normal
-"text packets" can override this setting.
-.TP
-.B \-P
-The input file specified by \fB\-i\fP is a binary file produced using libpcap
-(i.e., tcpdump version 3).  Packets are read from this file as being input
-(for rule purposes).  An interface maybe specified using \fB\-I\fP.
-.TP
-.B \-S
-The input file is to be in "snoop" format (see RFC 1761).  Packets are read
+.Dq text packets
+can override this setting.
+.It Fl P
+The input file is in 
+the binary format produced using libpcap
+(i.e.,
+.Xr tcpdump
+version 3).  Packets are read from this file as being input
+(for rule purposes).  An interface may be specified using
+.Fl I .
+.It Fl S
+The input file is in
+.Dq snoop
+format (see RFC 1761).  Packets are read
 from this file and used as input from any interface.  This is perhaps the
 most useful input type, currently.
-.TP
-.B \-T
-The input file is to be text output from tcpdump.  The text formats which
-are currently supported are those which result from the following tcpdump
+.It Fl T
+The input file is text output from
+.Xr tcpdump .
+The text formats which
+are currently supported are those which result from the following
+.Xr tcpdump
 option combinations:
-.PP
-.nf
-		tcpdump -n
-		tcpdump -nq
-		tcpdump -nqt
-		tcpdump -nqtt
-		tcpdump -nqte
-.fi
-.LP
-.TP
-.B \-H
-The input file is to be hex digits, representing the binary makeup of the
-packet.  No length correction is made, if an incorrect length is put in
+.Bd -literal -offset indent
+tcpdump -n
+tcpdump -nq
+tcpdump -nqt
+tcpdump -nqtt
+tcpdump -nqte
+.Ed
+.It Fl H
+The input file is hex digits, representing the binary makeup of the
+packets.  No length correction is made if an incorrect length is put in
 the IP header.
-.TP
-.B \-X
+.It Fl X
 The input file is composed of text descriptions of IP packets.
-.TP
-.B \-E
-The input file is to be text output from etherfind.  The text formats which
+.It Fl E
+The input file is text output from etherfind.  The text formats which
 are currently supported are those which result from the following etherfind
 option combinations:
-.PP
-.nf
-		etherfind -n
-		etherfind -n -t
-.fi
-.LP
-.TP
-.BR \-i \0<filename>
+.Bd -literal -offset indent
+etherfind -n
+etherfind -n -t
+.Ed
+.It Fl i Ar filename
 Specify the filename from which to take input.  Default is stdin.
-.TP
-.BR \-r \0<filename>
+.It Fl r Ar filename
 Specify the filename from which to read filter rules.
-.SH FILES
-.SH SEE ALSO
-ipf(8), ipf(5), snoop(1m), tcpdump(8), etherfind(8c)
-.SH BUGS
-Not all of the input formats are sufficiently capable of introducing a
-wide enough variety of packets for them to be all useful in testing.
+.El
+.Sh SEE ALSO
+.Xr snoop 1m ,
+.Xr ipf 5 ,
+.Xr ipf 8 ,
+.Xr tcpdump 8 ,
+.Xr etherfind 8c
+.Sh BUGS
+Not all of the input formats are capable of introducing a
+wide enough variety of packets to be useful in testing.