contrib/ipfilter/man/ipftest.1

   1 .\" $FreeBSD$
   2 .TH ipftest 1
   3 .SH NAME
   4 ipftest \- test packet filter rules with arbitrary input.
   5 .SH SYNOPSIS
   6 .B ipftest
   7 [
   8 .B \-6bCdDoRvx
   9 ] [
  10 .B \-F
  11 input-format
  12 ] [
  13 .B \-i
  14 <filename>
  15 ] [
  16 .B \-I
  17 interface
  18 ] [
  19 .B \-l
  20 <filename>
  21 ] [
  22 .B \-N
  23 <filename>
  24 ] [
  25 .B \-P
  26 <filename>
  27 ] [
  28 .B \-r
  29 <filename>
  30 ] [
  31 .B \-S
  32 <ip_address>
  33 ] [
  34 .B \-T
  35 <optionlist>
  36 ]
  37 .SH DESCRIPTION
  38 .PP
  39 \fBipftest\fP is provided for the purpose of being able to test a set of
  40 filter rules without having to put them in place, in operation and proceed
  41 to test their effectiveness.  The hope is that this minimises disruptions
  42 in providing a secure IP environment.
  43 .PP
  44 \fBipftest\fP will parse any standard ruleset for use with \fBipf\fP,
  45 \fBipnat\fP and/or \fBippool\fP
  46 and apply input, returning output as to the result.  However, \fBipftest\fP
  47 will return one of three values for packets passed through the filter:
  48 pass, block or nomatch.  This is intended to give the operator a better
  49 idea of what is happening with packets passing through their filter
  50 ruleset.
  51 .PP
  52 At least one of \fB\-N\fP, \fB-P\fP or \fB\-r\fP must be specified.
  53 .SH OPTIONS
  54 .TP
  55 .B \-6
  56 Use IPv6.
  57 .TP
  58 .B \-b
  59 Cause the output to be a brief summary (one-word) of the result of passing
  60 the packet through the filter; either "pass", "block" or "nomatch".
  61 This is used in the regression testing.
  62 .TP
  63 .B \-C
  64 Force the checksums to be (re)calculated for all packets being input into
  65 \fBipftest\fP.  This may be necessary if pcap files from tcpdump are being
  66 fed in where there are partial checksums present due to hardware offloading.
  67 .TP
  68 .B \-d
  69 Turn on filter rule debugging.  Currently, this only shows you what caused
  70 the rule to not match in the IP header checking (addresses/netmasks, etc).
  71 .TP
  72 .B \-D
  73 Dump internal tables before exiting.
  74 This excludes log messages.
  75 .TP
  76 .B \-F
  77 This option is used to select which input format the input file is in.
  78 The following formats are available: etherfind, hex, pcap, snoop, tcpdump,text.
  79 .RS
  80 .TP
  81 .B etherfind
  82 The input file is to be text output from etherfind.  The text formats which
  83 are currently supported are those which result from the following etherfind
  84 option combinations:
  85 .PP
  86 .nf
  87                 etherfind -n
  88                 etherfind -n -t
  89 .fi
  90 .TP
  91 .B hex
  92 The input file is to be hex digits, representing the binary makeup of the
  93 packet.  No length correction is made, if an incorrect length is put in
  94 the IP header.  A packet may be broken up over several lines of hex digits,
  95 a blank line indicating the end of the packet.  It is possible to specify
  96 both the interface name and direction of the packet (for filtering purposes)
  97 at the start of the line using this format: [direction,interface]  To define
  98 a packet going in on le0, we would use \fB[in,le0]\fP - the []'s are required
  99 and part of the input syntax.
 100 .HP
 101 .B pcap
 102 The input file specified by \fB\-i\fP is a binary file produced using libpcap
 103 (i.e., tcpdump version 3).  Packets are read from this file as being input
 104 (for rule purposes).  An interface maybe specified using \fB\-I\fP.
 105 .TP
 106 .B snoop
 107 The input file is to be in "snoop" format (see RFC 1761).  Packets are read
 108 from this file and used as input from any interface.  This is perhaps the
 109 most useful input type, currently.
 110 .TP
 111 .B tcpdump
 112 The input file is to be text output from tcpdump.  The text formats which
 113 are currently supported are those which result from the following tcpdump
 114 option combinations:
 115 .PP
 116 .nf
 117                 tcpdump -n
 118                 tcpdump -nq
 119                 tcpdump -nqt
 120                 tcpdump -nqtt
 121                 tcpdump -nqte
 122 .fi
 123 .TP
 124 .B text
 125 The input file is in \fBipftest\fP text input format.
 126 This is the default if no \fB\-F\fP argument is specified.
 127 The format used is as follows:
 128 .nf
 129         "in"|"out" "on" if ["tcp"|"udp"|"icmp"]
 130                 srchost[,srcport] dsthost[,destport] [FSRPAU]
 131 .fi
 132 .PP
 133 This allows for a packet going "in" or "out" of an interface (if) to be
 134 generated, being one of the three main protocols (optionally), and if
 135 either TCP or UDP, a port parameter is also expected.  If TCP is selected,
 136 it is possible to (optionally) supply TCP flags at the end.  Some examples
 137 are:
 138 .nf
 139         # a UDP packet coming in on le0
 140         in on le0 udp 10.1.1.1,2210 10.2.1.5,23
 141         # an IP packet coming in on le0 from localhost - hmm :)
 142         in on le0 localhost 10.4.12.1
 143         # a TCP packet going out of le0 with the SYN flag set.
 144         out on le0 tcp 10.4.12.1,2245 10.1.1.1,23 S
 145 .fi
 146 .LP
 147 .RE
 148 .DT
 149 .TP
 150 .BR \-i \0<filename>
 151 Specify the filename from which to take input.  Default is stdin.
 152 .TP
 153 .BR \-I \0<interface>
 154 Set the interface name (used in rule matching) to be the name supplied.
 155 This is useful where it is
 156 not otherwise possible to associate a packet with an interface.  Normal
 157 "text packets" can override this setting.
 158 .TP
 159 .BR \-l \0<filename>
 160 Dump log messages generated during testing to the specified file.
 161 .TP
 162 .BR \-N \0<filename>
 163 Specify the filename from which to read NAT rules in \fBipnat\fP(5) format.
 164 .TP
 165 .B \-o
 166 Save output packets that would have been written to each interface in
 167 a file /tmp/\fIinterface_name\fP in raw format.
 168 .TP
 169 .BR \-P \0<filename>
 170 Read IP pool configuration information in \fBippool\fP(5) format from the
 171 specified file.
 172 .TP
 173 .BR \-r \0<filename>
 174 Specify the filename from which to read filter rules in \fBipf\fP(5) format.
 175 .TP
 176 .B \-R
 177 Don't attempt to convert IP addresses to hostnames.
 178 .TP
 179 .BR \-S \0<ip_address>
 180 The IP address specifived with this option is used by ipftest to determine
 181 whether a packet should be treated as "input" or "output".  If the source
 182 address in an IP packet matches then it is considered to be inbound.  If it
 183 does not match then it is considered to be outbound.  This is primarily
 184 for use with tcpdump (pcap) files where there is no in/out information
 185 saved with each packet.
 186 .TP
 187 .BR \-T \0<optionlist>
 188 This option simulates the run-time changing of IPFilter kernel variables
 189 available with the \fB\-T\fP option of \fBipf\fP.
 190 The optionlist parameter is a comma separated list of tuning
 191 commands.  A tuning command is either "list" (retrieve a list of all variables
 192 in the kernel, their maximum, minimum and current value), a single variable
 193 name (retrieve its current value) and a variable name with a following
 194 assignment to set a new value.  See \fBipf\fP(8) for examples.
 195 .TP
 196 .B \-v
 197 Verbose mode.  This provides more information about which parts of rule
 198 matching the input packet passes and fails.
 199 .TP
 200 .B \-x
 201 Print a hex dump of each packet before printing the decoded contents.
 202 .SH SEE ALSO
 203 ipf(5), ipf(8), snoop(1m), tcpdump(8), etherfind(8c)
 204 .SH BUGS
 205 Not all of the input formats are sufficiently capable of introducing a
 206 wide enough variety of packets for them to be all useful in testing.