dist/ipf/man/ipftest.1

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