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; they must be IPv4 addresses.
  43             You may also change PARTS, PERPART or MTU if you like.
  44         * Say `make -j2 all'.  This will generate the test data sets.
  45             This will take a while.  Vary the -j for your system.
  46             If you want to do a quick test first, you can say
  47             `make few' first, instead.
  48         * Copy send-1.pcap and send-all.pcap to the sending machine.
  49         * Copy on-dest.sh to the to the receiving machine.
  50
  51 2. Run the first, small test
  52         * On the receiving machine, say, as root,
  53                 ./on-dest.sh 1
  54             and leave it running.
  55         * On the sending machine, say, as root,
  56                 tcpreplay -m 1 <send-1.pcap
  57             The -m 1 option makes tcpreplay send the packets at one a
  58             second (they are generated as if they were captured at one
  59             a second); this avoids flooding the network, which causes
  60             congestion, packet loss and maybe other randomness.
  61             This will take (by default) 100 seconds.
  62         * When it has finished, kill on-dest.sh.  Copy the
  63             file recv-1.pcap back to your analysis machine, and
  64             there say `make analyse' (or `make anal' if you prefer).
  65         * This will generate `recv-1.log' and `recv-1.diff'.
  66             Read the diff and see if it's by and large working.
  67             See below for information about interpreting the various files.
  68
  69 3. Run the full test
  70         Do the same as step 2, but instead of `1', say `all'
  71         everywhere.
  72
  73
  74 FILES INVOLVED
  75    Those made by `make generate':
  76         send-X.pcap     `pcap' format raw test data files
  77                          (feed this to tcpreplay -m 1)
  78         send-X.log      tcpdump's interpretation of the test data
  79                          with line numbers added
  80         send-X.why      The generator's explanations (ha ha) of
  81                          what the test data is
  82         on-dest.sh      Script for running tcpdump on the destination
  83    You really want to be paying attention to the ones where
  84    X is `1' and `all'.  The others, 2 onwards, are all in
  85    `all' and it'll be easier to take them all at once.
  86
  87    Those supposedly captured at the destination
  88         recv-X.pcap     `pcap' format raw received packets
  89
  90    Those made during the analysis:
  91         recv-X.log      tcpdump's interpretation of the received packets
  92         recv-X.diff     difference between send-*.log and recv-*.log
  93
  94
  95 INTERPRETATION OF THE TEXT FILES - EXAMPLE
  96
  97 Here is an example of a diff you might see:
  98
  99 @@ -23,12 +15,7 @@
 100                          453e 001c f194 0000 ff02 17bf ac12 2d23
 101                          ac12 2d06 1029 36f1 7daa 3b3b 0000 0000
 102                          0000 0000 0000 0000 0000 0000 0000
 103 -5
 104 -    172.18.45.35 > 172.18.45.6: icmp: type-#75 (DF) [tos 0xe7] (ttl 255, id 30130)
 105 -                        45e7 0023 75b2 4000 ff01 52f2 ac12 2d23
 106 -                        ac12 2d06 4b8c 34ba 4844 ce2d 1bde 5caf
 107 -                        0ab9 e600 0000 0000 0000 0000 0000
 108 -6
 109 +4
 110      172.18.45.35.21814 > 172.18.45.6.21814: udp 12 (ttl 255, id 26421)
 111                          4500 0028 6735 0000 ff11 a241 ac12 2d23
 112
 113 This means that a packet which was sent, was not received.  You can
 114 see the actual hex contents, and tcpdump's interpretation, in the
 115 lines marked with `-'.  The changed numbers at the left are just the
 116 packet numbers.  You can use the numbers marked with `-' to find the
 117 corresponding packet in the other files.  Ignore the numbers marked
 118 with `+', they aren't useful.  In this case, it's packet 5 that's
 119 missing.  So, we can look in send-1.why or send-rest.why, as
 120 appropriate, and see this:
 121
 122    1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
 123                  (any) type=75 (junk) l=11 code=140
 124        45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d1bde5caf0ab9e6
 125
 126 In send-all.why, these are prepended by another line number, which is
 127 the one you should use, so it would look like this:
 128
 129      5     1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
 130                          (any) type=75 (junk) l=11 code=140
 131               45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d\
 132                                                          1bde5caf0ab9e6
 133
 134 (The other two numbers are the batch and line within the batch.
 135 I have wrapped this here with \ and some indentation for ease of
 136 reading.)
 137
 138 You can see the hex dump of the packet, which is the same as the one
 139 in the tcpdump output, except that the tcpdump one has some extra
 140 padding with zeroes to bring it to the minimum ethernet frame size.
 141 You can also see some notes that the generator made:
 142
 143   tos=0xe7 id=30130     The IP TOS and ID
 144   df                    The Don't Fragment flag was set (there would
 145                          be `frag' here if it was fragmented)
 146   (!any)                It picked a known next layer up [`(!any)']
 147   proto=icmp[1]          and the one it picked was protocol 1, icmp
 148   (any) type=75         It picked an unknown next layer up, icmp type no.75
 149   (junk) l=11            and gave it 11 bytes of junk payload
 150   code=140               and an icmp code value of 140
 151
 152
 153 Some more examples from send-*.why and send-*.log files:
 154
 155     17     2 7  tos=0x14 id=56320 !df (!any) proto=tcp[6] source_port=37365 \
 156                 dest_port=52759 (connect) seq=0xab57703f ack=0x6c55ec70 \
 157                 window=0xdd21 !p u urg=0xce6c (noopt) (!optxpad) !unexpdata \
 158                 csumerror=0x9a18
 159
 160     172.18.45.35.37365 > 172.18.45.6.52759: S 2874634303:2874634303(0) \
 161                       win 56609 urg 52844 [tos 0x14] (ttl 255, id 56320)
 162
 163 This is a TCP SYN packet with urgent data, .  However, it has been
 164 generated with an invalid checksum: the checksum in the packet has
 165 been XOR'd with 0x9a18.
 166
 167     59     6 9  tos=0x2f id=15886 !df (!any) proto=tcp[6] source_port=52650 \
 168                 dest_port=37162 (data) seq=0xec912ceb ack=0x8cd28874 \
 169                 window=1 !p !u urg=0xe427 (badopt) l=30 l=12
 170
 171     172.18.45.35.52650 > 172.18.45.6.37162: . 3968937195:3968937207(12) \
 172                ack 2362607732 win 1 <[bad opt]> [tos 0x2f] (ttl 255, id 15886)
 173
 174 More TCP.  This time it's a data packet.  The urgent flag isn't set
 175 (though the urgent pointer value is nonzero), and it has 30 bytes of
 176 invalid option data and 12 bytes of actual data.
 177
 178    134    7 14  tos=0x4e id=12035 df (!any) proto=ip[4] \
 179                 source=206.78.180.32 dest=252.75.191.229 \
 180                 tos=0x94 id=14197 df (!any) proto=udp[17] (reply) \
 181                 port=remailck[50] port=20463 (resp-auth) auth=0xabcf
 182
 183     172.18.45.35 > 172.18.45.6: 206.78.180.32.50 > 252.75.191.229.20463: \
 184                 udp 12 (DF) [tos 0x94] (ttl 255, id 14197) (DF) \
 185                 [tos 0x4e] (ttl 255, id 12035)
 186
 187 IPv4 tunnelling.  The outer packet has TOS 4e and ID 12035.  Both The
 188 inner packet is a reply from a UDP service `(reply)' from a well-known
 189 port to a random port.  The packet is according to the RFC1339 mail
 190 check service on port 50, requesting authorisation from the client;
 191 the server's authorisations' supported bitmap is allegedly 0xabcf.
 192
 193     15    1 15  tos=0x5b id=61344 df (!any) proto=udp[17] (random) \
 194                 port=20500 port=11701 l=2
 195
 196     172.18.45.35.20500 > 172.18.45.6.11701: udp 2 (DF) [tos 0x5b] \
 197                 (ttl 255, id 61344)
 198
 199 This is a generic UDP packet from one random port (20500 in this case)
 200 to another (11701).  It has 2 bytes of data.
 201
 202     59    3 19  tos=0xa0 id=36385 !df (!any) proto=udp[17] (servers) \
 203                 port=dhcpserv[67] (!any) op=reply[2] (!any) htype=ethernet[1] \
 204                 hops=88 xid=0xd31e0dfe secs=149 flags=0x80 \
 205                 ciaddr=70.114.113.11 yiaddr=38.225.152.221 \
 206                 siaddr=98.91.71.52 giaddr=128.20.46.24 \
 207                 sname="yc3g27vvukig44qsx8lpud4e1.dbxxidju2ok3kipebqkd.pd2x\
 208                 89rdmrfz1dr" file="/o.h22gsn7s44yq2llx.v_-a+s_f421_iijnroam\
 209                 krpm7b674t7w.y3lfw8immrjaqpsu7.a.x.nev+j3hi/" (nocsum)
 210
 211 This is a UDP packet between well-known ports `(servers)'; the
 212 generator only generates such packets with identical source and
 213 destination ports, in this case the DHCP server port.  (Usually DHCP
 214 servers would talk to clients, not to each oehter.)  There is a DHCP
 215 packet whose details you can see.  `(nocsum)' indicates that the UDP
 216 checksum field in the UDP header is set to 0, indicating that no
 217 checksum is to be performed.
 218
 219
 220 # This file is part of vinegar-ip, tools for IP transparency testing.
 221 # vinegar-ip is Copyright (C) 2002 Ian Jackson
 222 #
 223 # This program is free software; you can redistribute it and/or modify
 224 # it under the terms of the GNU General Public License as published by
 225 # the Free Software Foundation; either version 2, or (at your option)
 226 # any later version.
 227 #
 228 # This program is distributed in the hope that it will be useful,
 229 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 230 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 231 # GNU General Public License for more details.
 232 #
 233 # You should have received a copy of the GNU General Public License
 234 # along with this program; if not, write to the Free Software Foundation,
 235 # Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 236 #
 237 # $Id$
 238
 239
 240  $Id$