contrib/ipfilter/man/ipftest.1

   1 .TH ipftest 1
   2 .SH NAME
   3 ipftest \- test packet filter rules with arbitrary input.
   4 .SH SYNOPSIS
   5 .B ipftest
   6 [
   7 .B \-vbdPRSTEHX
   8 ] [
   9 .B \-I
  10 interface
  11 ]
  12 .B \-r
  13 <filename>
  14 [
  15 .B \-i
  16 <filename>
  17 ] [
  18 .B \-s
  19 <ipaddress>
  20 ]
  21 .SH DESCRIPTION
  22 .PP
  23 \fBipftest\fP is provided for the purpose of being able to test a set of
  24 filter rules without having to put them in place, in operation and proceed
  25 to test their effectiveness.  The hope is that this minimises disruptions
  26 in providing a secure IP environment.
  27 .PP
  28 \fBipftest\fP will parse any standard ruleset for use with \fBipf\fP
  29 and apply input, returning output as to the result.  However, \fBipftest\fP
  30 will return one of three values for packets passed through the filter:
  31 pass, block or nomatch.  This is intended to give the operator a better
  32 idea of what is happening with packets passing through their filter
  33 ruleset.
  34 .PP
  35 When used without either of \fB\-S\fP, \fB\-T\fP or \fB\-E\fP,
  36 \fBipftest\fP uses its own text input format to generate "fake" IP packets.
  37 The format used is as follows:
  38 .nf
  39                 "in"|"out" "on" if ["tcp"|"udp"|"icmp"]
  40                         srchost[,srcport] dsthost[,destport] [FSRPAU]
  41 .fi
  42 .PP
  43 This allows for a packet going "in" or "out" of an interface (if) to be
  44 generated, being one of the three main protocols (optionally), and if
  45 either TCP or UDP, a port parameter is also expected.  If TCP is selected,
  46 it is possible to (optionally) supply TCP flags at the end.  Some examples
  47 are:
  48 .nf
  49                 # a UDP packet coming in on le0
  50                 in on le0 udp 10.1.1.1,2210 10.2.1.5,23
  51                 # an IP packet coming in on le0 from localhost - hmm :)
  52                 in on le0 localhost 10.4.12.1
  53                 # a TCP packet going out of le0 with the SYN flag set.
  54                 out on le0 tcp 10.4.12.1,2245 10.1.1.1,23 S
  55 .fi
  56 .SH OPTIONS
  57 .TP
  58 .B \-v
  59 Verbose mode.  This provides more information about which parts of rule
  60 matching the input packet passes and fails.
  61 .TP
  62 .B \-d
  63 Turn on filter rule debugging.  Currently, this only shows you what caused
  64 the rule to not match in the IP header checking (addresses/netmasks, etc).
  65 .TP
  66 .B \-b
  67 Cause the output to be a brief summary (one-word) of the result of passing
  68 the packet through the filter; either "pass", "block" or "nomatch".
  69 This is used in the regression testing.
  70 .TP
  71 .BR \-I \0<interface>
  72 Set the interface name (used in rule matching) to be the name supplied.
  73 This is useful with the \fB\-P, \-S, \-T\fP and \fB\-E\fP options, where it is
  74 not otherwise possible to associate a packet with an interface.  Normal
  75 "text packets" can override this setting.
  76 .TP
  77 .B \-P
  78 The input file specified by \fB\-i\fP is a binary file produced using libpcap
  79 (i.e., tcpdump version 3).  Packets are read from this file as being input
  80 (for rule purposes).  An interface maybe specified using \fB\-I\fP.
  81 .TP
  82 .B \-R
  83 Remove rules rather than load them.  This is not a toggle option, so once
  84 set, it cannot be reset by further use of -R.
  85 .TP
  86 .B \-S
  87 The input file is to be in "snoop" format (see RFC 1761).  Packets are read
  88 from this file and used as input from any interface.  This is perhaps the
  89 most useful input type, currently.
  90 .TP
  91 .B \-T
  92 The input file is to be text output from tcpdump.  The text formats which
  93 are currently supported are those which result from the following tcpdump
  94 option combinations:
  95 .PP
  96 .nf
  97                 tcpdump -n
  98                 tcpdump -nq
  99                 tcpdump -nqt
 100                 tcpdump -nqtt
 101                 tcpdump -nqte
 102 .fi
 103 .LP
 104 .TP
 105 .B \-H
 106 The input file is to be hex digits, representing the binary makeup of the
 107 packet.  No length correction is made, if an incorrect length is put in
 108 the IP header.  A packet may be broken up over several lines of hex digits,
 109 a blank line indicating the end of the packet.  It is possible to specify
 110 both the interface name and direction of the packet (for filtering purposes)
 111 at the start of the line using this format: [direction,interface]  To define
 112 a packet going in on le0, we would use \fB[in,le0]\fP - the []'s are required
 113 and part of the input syntax.
 114 .TP
 115 .B \-X
 116 The input file is composed of text descriptions of IP packets.
 117 .TP
 118 .B \-E
 119 The input file is to be text output from etherfind.  The text formats which
 120 are currently supported are those which result from the following etherfind
 121 option combinations:
 122 .PP
 123 .nf
 124                 etherfind -n
 125                 etherfind -n -t
 126 .fi
 127 .LP
 128 .TP
 129 .BR \-i \0<filename>
 130 Specify the filename from which to take input.  Default is stdin.
 131 .TP
 132 .BR \-r \0<filename>
 133 Specify the filename from which to read filter rules.
 134 .TP
 135 .BR \-s \0<ipaddress>
 136 Where the input format is incapable of telling \fBipftest\fP whther a packet is
 137 going in or out, setting this option to an IP address results in the direction
 138 being set to out if the source matches or in if the destination matches.
 139 .SH SEE ALSO
 140 ipf(5), ipf(8), snoop(1m), tcpdump(8), etherfind(8c)
 141 .SH BUGS
 142 Not all of the input formats are sufficiently capable of introducing a
 143 wide enough variety of packets for them to be all useful in testing.