Hi folks,

This directory contains source code for the first alpha release of
sting, which is a TCP-based network measurement tool.  Its ugly,
kludgey, code only a grad student could love... but it works :-) 

In this first release, sting estimates one-way packet loss rates
basically as described in the 1999 USITS paper, "Sting: a TCP-based
Network Measurement Tool" available off my Web page
(http://www.cs.washington.edu/homes/savage/).  We are actively looking
at providing some other measurement services (propagation delay,
one-way queuing delay and one-way bottleneck bandwidths) in future
releases. 

This code base was largely developed and tested on FreeBSD (although
I've only tried it on FreeBSD 3.1).  I've recently (last night) ported
the code to a modern version of Linux (whatever comes in RH6.0) and it
seems to work.


GETTING STARTED
---------------
To compile and run sting, you'll need three things:

  1) a compiled version of McCanne, Leres and Jacobson's libpcap library
    (I've included the version of this distribution I've used, but the
    most up-to-date version can be found at
    ftp://ftp.ee.lbl.gov.libpcap.tar.Z)

  Either: 

  2a) a FreeBSD kernel compiled with support for BPF and firewalls.  I
      suggest compiling a kernel with the following options in your config
      file:

      options         IPFIREWALL                   #firewall
      options         IPFIREWALL_DEFAULT_TO_ACCEPT #allow everything by default
      options         NMBCLUSTERS=8192

      pseudo-device   bpfilter 16                  #Berkeley packet filter

  or

  2b) or a modern Linux kernel compiled with support for firewalls.  I 
      don't know Linux well enough to tell you how to do this.
      However, if /sbin/ipchains -L doesn't give you a nice message
      then your kernel probably isn't right.  Find a penguin person.  

  3) A root shell.  sting must be run by root or suid root because it
     writes raw sockets, installs firewall filters and packet filters.

     (Note: sting has not been checked for potential security exploits
      such as buffer overflow attacks, so should probably not be made
      available suid in an untrusted environment).

USING STING
-----------
The basic syntax is pretty simple:

sting [-p port] [-c count] [-f distribution] [-m mean] [-v] targethost

where port refers to a particular TCP port on the target host, count
is the number of packets to send, distribution is one of
"exponential", "uniform", or "periodic" and refers to the
distribution used to generate the spacing between packets, and mean
specifies the mean of the distribution (or in the case of the periodic
distribution, the period).  The -v flag specifies verbose mode which
prints additional information (including feedback about progress). 

If no options are specified, sting defaults to sending 100 packets of
41 bytes each (1 data byte and 40 bytes of TCP/IP headers) to port 80
(http), spaced according to a uniform distribution with a mean of 0.1
seconds (100ms). 

QUICK TIP:  For testing Windows clients try using port 139 (netbios)


Here is the output from a sample session:

[savage1]# ./sting www.cnn.com
Connection setup took 80 ms
src = 128.95.219.227:10241 (1753156211)
dst = 207.25.71.25:80 (347132509)
dataSent = 100, dataReceived = 100
acksSent = 100, acksReceived = 100
Forward loss rate = 0.000000
Reverse loss rate = 0.000000
634 packets received by filter
0 packets dropped by kernel

The "Forward loss rate" refers to the one-way loss rate on the path
from the client machine (in this case savage1) TO the target machine
(www.cnn.com).  The "Reverse loss rate" refers to the one-way loss
rate on the path from the target machine BACK to the client machine.
In this example, no packets have been lost.

(Note that the number 634 packets received by filter is wrong and
reflects some confusion in FreeBSD's packet filter machinery)

LICENSING & LIABILITY
--------------------------
sting is being released under a BSD-style license and therefore can be
used for any and all purposes by any and all comers, the only
restriction being that the copyright information must be maintained
and credit provided to the contributors.

Going along with that is the abdication of all liability on my part,
on the university's part, and on the part of any and all external
contributors.  The legalese is in the source files for you to read but
in my mind it roughly translates to:  

"Look, this code was written in the wee hours of the night by
a financially un-compensated grad student who should have been working
on his thesis and whose last awarded degree was in History, so its
your own fault if you depend on this software to do what is claimed,
let alone work, without verifying it yourself and certainly don't
blame us if it doesn't.  So there."   

That being said, if you do use this code and find problems or make
improvements PLEASE send them back to me so I can improve
sting for later releases.  If you experience problems, please specify
the operating system you're using, the DNS name and IP address of the
target host, how sting failed, and (ideally) a tcpdump trace of the
complete conversation between the host pairs.  If you're _seriously_
considering adding services or doing a port, please send me a note so
I can coordinate and avoid the duplication of effort.


Have fun, and be careful out there.


- Stefan

savage@cs.washington.edu
http://www.cs.washington.edu/homes/savage


SPECIAL THANKS
--------------
To Lawrence Berkeley Labs and the various folks who worked on libpcap
(which we use) and tcpdump (from which we've borrowed a few files:
gmt2local.c, gmt2local.h, setsignal.c, setsignal.h).  Also thanks to
the Internet Society and the authors of RFC 2330, from which the
contents of the files distribution.c and distribution.h were taken.

Thanks to Neal Cardwell, David Wetherall and Tom Anderson, who all
provided feedback and encouragement to make sting actually happen.

Finally, a very special thanks to USENIX which has provided funding for
some of my work in this area (via the Student Research Grants program).


KNOWN ISSUES
------------
- Packet sizing does not work reliably in this release.  The algorithm
  described for sequence number overlapping in the USITS paper is buggy
  and we have removed it.  The current release sends packets
  back-to-back and can quickly overwhelm remote receiver buffers.  We have 
  an alternative algorithm that does work, albeit with only modest
  improvements in buffer reduction (2x), but it isn't fully 
  implemented and tested yet.  In the interim, either stick with the
  default size of 41 bytes, or reduce the number of packets sent (-c)
  per round when you encounter problems with larger packets.

- Some web servers will issue a reset if connect() or read() times out
  thereby preventing sting from collecting a complete reading.  sting
  will report when this happens, however for machines with short
  duration timeouts this can be problematic.  We have developed a
  potential fix, but it isn't yet implemented because its pretty ugly.
  For the interim, either send a smaller number of packets per trial or
  reduce the inter-arrival time mean to reduce the overall time of a
  sting measurement. 

- Some embedded devices do not support fast retransmit or cannot handle
  large numbers of our-of-order data packets.  Please be careful because
  some of these devices will crash under some of sting's inputs.

- The finger service of a... ahem... popular router vendor does not
  depend on user input and simply sends its data and performs an
  abortive close.  This service therefore cannot be used by sting.  

- At least one (very old) version of MacOS appears to not acknowledge
  out-of-order packets.

- If, somehow, you have an older version of sting that does not use
  the firewall interface, you should upgrade ASAP.  If your
  kernel is not appropriately modified you can easily desynchronize the
  TCP connection between the target host and your kernel, leading to
  "ack-storms" that can overwhelm short-RTT paths.



