Sort the summary

[vinegar-ip.git] / README

VINEGAR-IP - INSTRUCTIONS

This is a tool for IP transparency testing.  It allows you to send a
wide variety of `interesting' packets from one nominated machine to
another, and then examine what arrived to see if there are any
differences.

Up to 3 hosts are involved: one to do the test dataset generation and
analysis, as well as of course the sender and receiver.


WHAT YOU WILL NEED

* On the machine you generate and analyse the test data
        This Makefile and corresponding scripts
        GNU Make
        Tcl (as /usr/bin/tclsh)
        Perl (as /usr/bin/perl)
        OpenSSL (as `openssl' on PATH)
        tcpdump for converting trace files only, no root privilege
        GNU diff to look at the output
        Lots of CPU !  (the generation script is rather slow)

* On the sending machine
        tcpreplay (http://www.subterrain.net/tools/tcpreplay/,
                or from Debian testing 3.5.2002.  I used 1.0.1-1.1)
                and root privilege to run it

* On the receiving machine
        tcpdump for packet capture, and root privilege to run it
        The `on-dest.sh' script that this Makefile creates

It will be much better if the source and destination machines do not
have any other traffic.  If they do the tests may disrupt it, and
it'll get in the way of your analysis too.


WHAT TO DO

1. Generate the test data.
        * Edit this Makefile.
            You /must/ change SOURCE and DEST (or override them on
            the `make' command line, if you prefer); they must be
                <IPv4-address>/<ethernet-address>
            You may also change PARTS, PERPART or MTU if you like.
        * Say `make -j2 all'.  This will generate the test data sets.
            This will take a while.  Vary the -j for your system.
            If you want to do a quick test first, you can say
            `make few' first, instead.
        * Copy send-1.pcap and send-all.pcap to the sending machine.
        * Copy on-dest.sh and monitor.sh to the to the receiving machine.

2. Run the first, small test
        * On the receiving machine, say, as root,
                ./on-dest.sh 1 [-i <interface>]
            and leave it running.  Also, in a nice big window, say
                ./monitor.sh [-i <interface>]
            and leave that running too.  The default interface is
            the one that tcpdump picks by default.
        * On the sending machine, say, as root,
                tcpreplay -m 1 <send-1.pcap [-i <interface>]
            You should see the results in your monitoring window.
            This will take (by default) 100 seconds.  The -m 1 option
            makes tcpreplay send the packets at one a second (they are
            generated as if they were captured at one a second); this
            avoids flooding the network, which causes congestion,
            packet loss and maybe other randomness.
        * When it has finished, kill on-dest.sh and monitor.sh.
            Copy the file recv-1.pcap back to your analysis machine, and
            there say `make anal'.
        * This will generate
                recv-1.log  recv-1.diff  recv-1.mdiff  recv-1.summary
            Read the diffs and see if it's by and large working.
            See below for information about interpreting the various files.

3. Run the full test
        Do the same as step 2, but instead of `1', say `all'
        everywhere.


FILES INVOLVED
   Those made by `make generate':
        send-X.pcap     `pcap' format raw test data files
                         (feed this to tcpreplay -m 1)
        send-X.log      tcpdump's interpretation of the test data
                         with line numbers added
        send-X.why      The generator's explanations (ha ha) of
                         what the test data is
        on-dest.sh      Script for running tcpdump on the destination
                         to capture the packets as they come in
        monitor.sh      Script for running tcpdump on either end
                         for monitoring how it's going
   You really want to be paying attention to the ones where
   X is `1' and `all'.  `all' contains all the numbered parts,
   and it'll be easier to do them all at once.

   Those supposedly captured at the destination
        recv-X.pcap     `pcap' format raw received packets

   Those made during the analysis:
        recv-X.log      tcpdump's interpretation of the received packets
        recv-X.diff     difference between send-*.log and recv-*.log


INTERPRETATION OF THE TEXT FILES - EXAMPLE


You probably want to start with the recv-*.summary files.  Here's an
example line (folded and indented here to make it easier to read:

-7      80.4.4.56 > 212.22.195.1: 6.115.30.33.50 > 158.55.15.27.50: \
     udp 37 (DF) [tos 0xaf] (ttl 255, id 55590) [tos 0x62] (ttl ###, id 21803)

This means that packet no.7 either the packet didn't arrive, or
tcpdump produced different a summary line for the second packet.
The *.summary file is sorted crudely by the type of packet.

The recv-*.summary and recv-*.mdiff files DO NOT contain information
about packets whose bodies changed, unless tcpdump reported the change
in its summary.  recv-*.diff contains ALL changes, even to meaningless
parts of packets, except changes to the IP TTL and IP header checksum
(which are expected to change).

So, you can then look in recv-1.mdiff and recv-1.diff for more
information about packet no.7, if you're interested.  See below for
help on interpreting the diffs.


Here is an example of a diff you might see:

@@ -23,12 +15,7 @@
                         453e 001c f194 0000 ff02 17bf ac12 2d23
                         ac12 2d06 1029 36f1 7daa 3b3b 0000 0000
                         0000 0000 0000 0000 0000 0000 0000
-5
-    172.18.45.35 > 172.18.45.6: icmp: type-#75 (DF) [tos 0xe7] (ttl 255, id 30130)
-                        45e7 0023 75b2 4000 ff01 52f2 ac12 2d23
-                        ac12 2d06 4b8c 34ba 4844 ce2d 1bde 5caf
-                        0ab9 e600 0000 0000 0000 0000 0000
-6
+4
     172.18.45.35.21814 > 172.18.45.6.21814: udp 12 (ttl 255, id 26421)
                         4500 0028 6735 0000 ff11 a241 ac12 2d23

This means that a packet which was sent, was not received.  You can
see the actual hex contents, and tcpdump's interpretation, in the
lines marked with `-'.  The changed numbers at the left are just the
packet numbers.  You can use the numbers marked with `-' to find the
corresponding packet in the other files.  Ignore the numbers marked
with `+', they aren't useful.  In this case, it's packet 5 that's
missing.  So, we can look in send-1.why or send-all.why, as
appropriate, and see this:

batch  packet within batch
   |  /
   1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
                 (any) type=75 (junk) l=11 code=140
       45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d1bde5caf0ab9e6

or this:

        batch  packet within batch
           |  /
     5     1 5  tos=0xe7 id=30130 df (!any) proto=icmp[1] \
    /                    (any) type=75 (junk) l=11 code=140
  overall      45e7002375b24000ff0152f2ac122d23ac122d064b8c34ba4844ce2d\
 packet no.                                               1bde5caf0ab9e6

You can see the hex dump of the packet, which is the same as the one
in the tcpdump output, except that the tcpdump one has some extra
padding with zeroes to bring it to the minimum ethernet frame size.
You can also see some notes that the generator made:

  tos=0xe7 id=30130     The IP TOS and ID
  df                    The Don't Fragment flag was set (there would
                         be `frag' here if it was fragmented)
  (!any)                It picked a known next layer up [`(!any)']
  proto=icmp[1]          and the one it picked was protocol 1, icmp
  (any) type=75         It picked an unknown next layer up, icmp type no.75
  (junk) l=11            and gave it 11 bytes of junk payload
  code=140               and an icmp code value of 140


Some more examples from send-*.why and send-*.log files:

    17     2 7  tos=0x14 id=56320 !df (!any) proto=tcp[6] source_port=37365 \
                dest_port=52759 (connect) seq=0xab57703f ack=0x6c55ec70 \
                window=0xdd21 !p u urg=0xce6c (noopt) (!optxpad) !unexpdata \
                csumerror=0x9a18

    172.18.45.35.37365 > 172.18.45.6.52759: S 2874634303:2874634303(0) \
                      win 56609 urg 52844 [tos 0x14] (ttl 255, id 56320)

This is a TCP SYN packet with urgent data, .  However, it has been
generated with an invalid checksum: the checksum in the packet has
been XOR'd with 0x9a18.

    59     6 9  tos=0x2f id=15886 !df (!any) proto=tcp[6] source_port=52650 \
                dest_port=37162 (data) seq=0xec912ceb ack=0x8cd28874 \
                window=1 !p !u urg=0xe427 (badopt) l=30 l=12

    172.18.45.35.52650 > 172.18.45.6.37162: . 3968937195:3968937207(12) \
               ack 2362607732 win 1 <[bad opt]> [tos 0x2f] (ttl 255, id 15886)

More TCP.  This time it's a data packet.  The urgent flag isn't set
(though the urgent pointer value is nonzero), and it has 30 bytes of
invalid option data and 12 bytes of actual data.

   134    7 14  tos=0x4e id=12035 df (!any) proto=ip[4] \
                source=206.78.180.32 dest=252.75.191.229 \
                tos=0x94 id=14197 df (!any) proto=udp[17] (reply) \
                port=remailck[50] port=20463 (resp-auth) auth=0xabcf

    172.18.45.35 > 172.18.45.6: 206.78.180.32.50 > 252.75.191.229.20463: \
                udp 12 (DF) [tos 0x94] (ttl 255, id 14197) (DF) \
                [tos 0x4e] (ttl 255, id 12035)

IPv4 tunnelling.  The outer packet has TOS 4e and ID 12035.  Both The
inner packet is a reply from a UDP service `(reply)' from a well-known
port to a random port.  The packet is according to the RFC1339 mail
check service on port 50, requesting authorisation from the client;
the server's authorisations' supported bitmap is allegedly 0xabcf.

    15    1 15  tos=0x5b id=61344 df (!any) proto=udp[17] (random) \
                port=20500 port=11701 l=2

    172.18.45.35.20500 > 172.18.45.6.11701: udp 2 (DF) [tos 0x5b] \
                (ttl 255, id 61344)

This is a generic UDP packet from one random port (20500 in this case)
to another (11701).  It has 2 bytes of data.

    59    3 19  tos=0xa0 id=36385 !df (!any) proto=udp[17] (servers) \
                port=dhcpserv[67] (!any) op=reply[2] (!any) htype=ethernet[1] \
                hops=88 xid=0xd31e0dfe secs=149 flags=0x80 \
                ciaddr=70.114.113.11 yiaddr=38.225.152.221 \
                siaddr=98.91.71.52 giaddr=128.20.46.24 \
                sname="yc3g27vvukig44qsx8lpud4e1.dbxxidju2ok3kipebqkd.pd2x\
                89rdmrfz1dr" file="/o.h22gsn7s44yq2llx.v_-a+s_f421_iijnroam\
                krpm7b674t7w.y3lfw8immrjaqpsu7.a.x.nev+j3hi/" (nocsum)

This is a UDP packet between well-known ports `(servers)'; the
generator only generates such packets with identical source and
destination ports, in this case the DHCP server port.  (Usually DHCP
servers would talk to clients, not to each oehter.)  There is a DHCP
packet whose details you can see.  `(nocsum)' indicates that the UDP
checksum field in the UDP header is set to 0, indicating that no
checksum is to be performed.


# This file is part of vinegar-ip, tools for IP transparency testing.
# vinegar-ip is Copyright (C) 2002 Ian Jackson
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
#
# $Id$


 $Id$