.\"     $OpenBSD: ipftest.1,v 1.16 2000/11/09 17:53:14 aaron Exp $
.Dd May 23, 1999
.Dt IPFTEST 1
.Os
.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 options are as follows:
.Bl -tag -width Ds
.It Fl v
Verbose mode.
This provides more information about which parts of rule
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).
.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.
.It Fl I Ar interface
Set the interface name (used in rule matching) to be the name supplied.
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
.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.
.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:
.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.
.It Fl X
The input file is composed of text descriptions of IP packets.
.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:
.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.
.It Fl r Ar filename
Specify the filename from which to read filter rules.
.El
.Sh SEE ALSO
.Xr ipf 5 ,
.Xr ipf 8 ,
.Xr tcpdump 8
.Sh BUGS
Not all of the input formats are capable of introducing a
wide enough variety of packets to be useful in testing.