README

   1 VINEGAR-IP - INSTRUCTIONS
   2
   3 This is a tool for IP transparency testing.  It allows you to send a
   4 wide variety of `interesting' packets from one nominated machine to
   5 another, and then examine what arrived to see if there are any
   6 differences.
   7
   8 Up to 3 hosts are involved: one to do the test dataset generation and
   9 analysis, as well as of course the sender and receiver.
  10
  11
  12 WHAT YOU WILL NEED
  13
  14 * On the machine you generate and analyse the test data
  15         This Makefile and corresponding scripts
  16         GNU Make
  17         Tcl (as /usr/bin/tclsh)
  18         Perl (as /usr/bin/perl)
  19         OpenSSL (as `openssl' on PATH)
  20         tcpdump for converting trace files only, no root privilege
  21         GNU diff to look at the output
  22         Lots of CPU !  (the generation script is rather slow)
  23
  24 * On the sending machine
  25         tcpreplay (http://www.subterrain.net/tools/tcpreplay/,
  26                 or from Debian testing 3.5.2002.  I used 1.0.1-1.1)
  27                 and root privilege to run it
  28
  29 * On the receiving machine
  30         tcpdump for packet capture, and root privilege to run it
  31         The `on-dest.sh' script that this Makefile creates
  32
  33 It will be much better if the source and destination machines do not
  34 have any other traffic.  If they do the tests may disrupt it, and
  35 it'll get in the way of your analysis too.
  36
  37
  38 WHAT TO DO
  39
  40 1. Generate the test data.
  41         * Edit this Makefile.
  42             You /must/ change SOURCE and DEST (or override them on
  43             the `make' command line, if you prefer); they must be
  44                 <IPv4-address>/<ethernet-address>
  45             The destination ethernet address should be the address
  46             of your next hop *router*, while the destination IPv4
  47             address should be that of the destination machine.
  48             You may also change PARTS, PERPART or MTU if you like.
  49         * Say `make -j2 all'.  This will generate the test data sets.
  50             This will take a while.  Vary the -j for your system.
  51             If you want to do a quick test first, you can say
  52             `make few' first, instead.
  53         * Copy send-1.pcap and send-all.pcap to the sending machine.
  54         * Copy on-dest.sh and monitor.sh to the to the receiving machine.
  55
  56 2. Run the first, small test
  57         * On the receiving machine, say, as root,
  58                 ./on-dest.sh 1 [-i <interface>]
  59             and leave it running.  Also, in a nice big window, say
  60                 ./monitor.sh [-i <interface>]
  61             and leave that running too.  The default interface is
  62             the one that tcpdump picks by default.
  63         * On the sending machine, say, as root,
  64                 tcpreplay -m 1 <send-1.pcap [-i <interface>]
  65             You should see the results in your monitoring window.
  66             This will take (by default) 100 seconds.  The -m 1 option
  67             makes tcpreplay send the packets at one a second (they are
  68             generated as if they were captured at one a second); this
  69             avoids flooding the network, which causes congestion,
  70             packet loss and maybe other randomness.
  71         * When it has finished, kill on-dest.sh and monitor.sh.
  72             Copy the file recv-1.pcap back to your analysis machine, and
  73             there say `make anal'.
  74         * This will generate
  75                 recv-1.log  recv-1.diff  recv-1.mdiff  recv-1.summary
  76             Read the diffs and see if it's by and large working.
  77             See below for information about interpreting the various files.
  78
  79 3. Run the full test
  80         Do the same as step 2, but instead of `1', say `all'
  81         everywhere.
  82
  83
  84 FILES INVOLVED
  85    Those made by `make generate':
  86         send-X.pcap     `pcap' format raw test data files
  87                          (feed this to tcpreplay -m 1)
  88         send-X.log      tcpdump's interpretation of the test data
  89                          with line numbers added
  90         send-X.why      The generator's explanations (ha ha) of
  91                          what the test data is
  92         on-dest.sh      Script for running tcpdump on the destination
  93                          to capture the packets as they come in
  94         monitor.sh      Script for running tcpdump on either end
  95                          for monitoring how it's going
  96    You really want to be paying attention to the ones where
  97    X is `1' and `all'.  `all' contains all the numbered parts,
  98    and it'll be easier to do them all at once.
  99
 100    Those supposedly captured at the destination
 101         recv-X.pcap     `pcap' format raw received packets
 102
 103    Those made during the analysis:
 104         recv-X.log      tcpdump's interpretation of the received packets
 105         recv-X.diff     difference between send-*.log and recv-*.log
 106
 107
 108 INTERPRETATION OF THE TEXT FILES - EXAMPLE
 109
 110
 111 You probably want to start with the recv-*.summary files.  Here's an
 112 example line (folded and indented here to make it easier to read:
 113
 114 -7      80.4.4.56 > 212.22.195.1: 6.115.30.33.50 > 158.55.15.27.50: \
 115      udp 37 (DF) [tos 0xaf] (ttl 255, id 55590) [tos 0x62] (ttl ###, id 21803)
 116
 117 This means that packet no.7 either the packet didn't arrive, or
 118 tcpdump produced different a summary line for the second packet.
 119 The *.summary file is sorted crudely by the type of packet.
 120
 121 The recv-*.summary and recv-*.mdiff files DO NOT contain information
 122 about packets whose bodies changed, unless tcpdump reported the change
 123 in its summary.  recv-*.diff contains ALL changes, even to meaningless
 124 parts of packets, except changes to the IP TTL and IP header checksum
 125 (which are expected to change).
 126
 127 So, you can then look in recv-1.mdiff and recv-1.diff for more
 128 information about packet no.7, if you're interested.  See below for
 129 help on interpreting the diffs.
 130
 131
 132 Here is an example of a diff you might see:
 133
 134 @@ -23,12 +15,7 @@
 135                          453e 001c f194 0000 ff02 17bf ac12 2d23
 136                          ac12 2d06 1029 36f1 7daa 3b3b 0000 0000
 137                          0000 0000 0000 0000 0000 0000 0000
 138 -5
 139 -    172.18.45.35 > 172.18.45.6: icmp: type-#75 (DF) [tos 0xe7] (ttl 255, id 30130)
 140 -                        45e7 0023 75b2 4000 ff01 52f2 ac12 2d23
 141 -                        ac12 2d06 4b8c 34ba 4844 ce2d 1bde 5caf
 142 -                        0ab9 e600 0000 0000 0000 0000 0000
 143 -6
 144 +4
 145      172.18.45.35.21814 > 172.18.45.6.21814: udp 12 (ttl 255, id 26421)
 146                          4500 0028 6735 0000 ff11 a241 ac12 2d23
 147
 148 This means that a packet which was sent, was not received.  You can
 149 see the actual hex contents, and tcpdump's interpretation, in the
 150 lines marked with `-'.  The changed numbers at the left are just the
 151 packet numbers.  You can use the numbers marked with `-' to find the
 152 corresponding packet in the other files.  Ignore the numbers marked
 153 with `+', they aren't useful.  In this case, it's packet 5 that's
 154 missing.  So, we can look in send-1.why or send-all.why, as
 155 appropriate, and see this:
 156
 157 batch  packet within batch
 158    |  /
 159    1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
 160                  (any) type=75 (junk) l=11 code=140
 161        45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d1bde5caf0ab9e6
 162
 163 or this:
 164
 165         batch  packet within batch
 166            |  /
 167      5     1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
 168     /                    (any) type=75 (junk) l=11 code=140
 169   overall      45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d\
 170  packet no.                                               1bde5caf0ab9e6
 171
 172 You can see the hex dump of the packet, which is the same as the one
 173 in the tcpdump output, except that the tcpdump one has some extra
 174 padding with zeroes to bring it to the minimum ethernet frame size.
 175 You can also see some notes that the generator made:
 176
 177   tos=0xe7 id=30130     The IP TOS and ID
 178   df                    The Don't Fragment flag was set (there would
 179                          be `frag' here if it was fragmented)
 180   (!any)                It picked a known next layer up [`(!any)']
 181   proto=icmp[1]          and the one it picked was protocol 1, icmp
 182   (any) type=75         It picked an unknown next layer up, icmp type no.75
 183   (junk) l=11            and gave it 11 bytes of junk payload
 184   code=140               and an icmp code value of 140
 185
 186
 187 Some more examples from send-*.why and send-*.log files:
 188
 189     17     2 7  tos=0x14 id=56320 !df (!any) proto=tcp[6] source_port=37365 \
 190                 dest_port=52759 (connect) seq=0xab57703f ack=0x6c55ec70 \
 191                 window=0xdd21 !p u urg=0xce6c (noopt) (!optxpad) !unexpdata \
 192                 csumerror=0x9a18
 193
 194     172.18.45.35.37365 > 172.18.45.6.52759: S 2874634303:2874634303(0) \
 195                       win 56609 urg 52844 [tos 0x14] (ttl 255, id 56320)
 196
 197 This is a TCP SYN packet with urgent data, .  However, it has been
 198 generated with an invalid checksum: the checksum in the packet has
 199 been XOR'd with 0x9a18.
 200
 201     59     6 9  tos=0x2f id=15886 !df (!any) proto=tcp[6] source_port=52650 \
 202                 dest_port=37162 (data) seq=0xec912ceb ack=0x8cd28874 \
 203                 window=1 !p !u urg=0xe427 (badopt) l=30 l=12
 204
 205     172.18.45.35.52650 > 172.18.45.6.37162: . 3968937195:3968937207(12) \
 206                ack 2362607732 win 1 <[bad opt]> [tos 0x2f] (ttl 255, id 15886)
 207
 208 More TCP.  This time it's a data packet.  The urgent flag isn't set
 209 (though the urgent pointer value is nonzero), and it has 30 bytes of
 210 invalid option data and 12 bytes of actual data.
 211
 212    134    7 14  tos=0x4e id=12035 df (!any) proto=ip[4] \
 213                 source=206.78.180.32 dest=252.75.191.229 \
 214                 tos=0x94 id=14197 df (!any) proto=udp[17] (reply) \
 215                 port=remailck[50] port=20463 (resp-auth) auth=0xabcf
 216
 217     172.18.45.35 > 172.18.45.6: 206.78.180.32.50 > 252.75.191.229.20463: \
 218                 udp 12 (DF) [tos 0x94] (ttl 255, id 14197) (DF) \
 219                 [tos 0x4e] (ttl 255, id 12035)
 220
 221 IPv4 tunnelling.  The outer packet has TOS 4e and ID 12035.  Both The
 222 inner packet is a reply from a UDP service `(reply)' from a well-known
 223 port to a random port.  The packet is according to the RFC1339 mail
 224 check service on port 50, requesting authorisation from the client;
 225 the server's authorisations' supported bitmap is allegedly 0xabcf.
 226
 227     15    1 15  tos=0x5b id=61344 df (!any) proto=udp[17] (random) \
 228                 port=20500 port=11701 l=2
 229
 230     172.18.45.35.20500 > 172.18.45.6.11701: udp 2 (DF) [tos 0x5b] \
 231                 (ttl 255, id 61344)
 232
 233 This is a generic UDP packet from one random port (20500 in this case)
 234 to another (11701).  It has 2 bytes of data.
 235
 236     59    3 19  tos=0xa0 id=36385 !df (!any) proto=udp[17] (servers) \
 237                 port=dhcpserv[67] (!any) op=reply[2] (!any) htype=ethernet[1] \
 238                 hops=88 xid=0xd31e0dfe secs=149 flags=0x80 \
 239                 ciaddr=70.114.113.11 yiaddr=38.225.152.221 \
 240                 siaddr=98.91.71.52 giaddr=128.20.46.24 \
 241                 sname="yc3g27vvukig44qsx8lpud4e1.dbxxidju2ok3kipebqkd.pd2x\
 242                 89rdmrfz1dr" file="/o.h22gsn7s44yq2llx.v_-a+s_f421_iijnroam\
 243                 krpm7b674t7w.y3lfw8immrjaqpsu7.a.x.nev+j3hi/" (nocsum)
 244
 245 This is a UDP packet between well-known ports `(servers)'; the
 246 generator only generates such packets with identical source and
 247 destination ports, in this case the DHCP server port.  (Usually DHCP
 248 servers would talk to clients, not to each oehter.)  There is a DHCP
 249 packet whose details you can see.  `(nocsum)' indicates that the UDP
 250 checksum field in the UDP header is set to 0, indicating that no
 251 checksum is to be performed.
 252
 253
 254 # This file is part of vinegar-ip, tools for IP transparency testing.
 255 # vinegar-ip is Copyright (C) 2002 Ian Jackson
 256 #
 257 # This program is free software; you can redistribute it and/or modify
 258 # it under the terms of the GNU General Public License as published by
 259 # the Free Software Foundation; either version 2, or (at your option)
 260 # any later version.
 261 #
 262 # This program is distributed in the hope that it will be useful,
 263 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 264 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 265 # GNU General Public License for more details.
 266 #
 267 # You should have received a copy of the GNU General Public License
 268 # along with this program; if not, write to the Free Software Foundation,
 269 # Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 270 #
 271 # $Id$
 272
 273
 274  $Id$