home | help 
SPP(1)				  User Manuals				  SPP(1)

NAME
     spp - calculates round trip time (RTT) from pcap files or live traffic cap-
     ture

SYNOPSIS
   File processing:
     spp  -a  address  -A address -f file -F file [-# hashcode | -n address | -N
     address |-p|-c|-m|-b|-O|-P|-H|-T]

   Live processing master:
     spp -a address -A address (-i interface | -r host ) (  -I	interface  |  -R
     slave_host   )   [-#   hashcode   |-g  usec  |  -n  address  |  -N  address
     |-p|-c|-m|-b|-O|-P|-H|-T]

   Remote slave:
     spp -a address -A address -s master_host -I interface [ -#  hashcode  |  -g
     usec | -l no.bytes | -t seconds | -n address | -N address ]

   Output:
     [pair count] timestamp rtt [spt] [OWDref2mon OWDmon2ref]

DESCRIPTION
     Building on the ideas presented in [1] and [2], spp provides frequently up-
     dated  RTT  estimates using IP traffic already present in the network.  spp
     estimates the RTT between two measurement points without requiring  precise
     time synchronisation between points. spp accurately estimates the RTT expe-
     rienced  by  any application's traffic without needing modifications to the
     application itself or the routers along the path.

     spp requires a capture of traffic at both ends (measurement points) of  the
     path  that  is  to be measured. From these captures spp identifies pairs of
     packets, one packet in each direction, from which RTT  can  be  calculated.
     The  reference  point  (REF)  is where the round trip is considered to have
     started from, with the monitor point (MON) being the far end of  the  round
     trip.  (For  example,  a ping might be considered to originate at REF while
     the ping target is MON.)

     These packet pairs are 'synthetic' in that the paired packets need not have
     any particular relationship to each other, except that one was seen travel-
     ling from REF to MON immediately before the other was seen travelling  from
     MON to REF.

     spp  works  with  tcpdump/pcap files previously captured at two points on a
     network, or alternatively, live capture on local and/or  remote  interfaces
     may be used.

OPTIONS
   General Options:
     -a     IP address near the reference point

     -A     IP address near the monitor point

     -n     NAT IP address near the reference point

     -N     NAT IP address near the monitor point

     -s     Put into slave mode and send to the master specified

     -o     Offset in seconds of clocks at the monitor point with respect to the
	    reference point.

     -d     Max  difference  of  timestamps  in seconds allowed between matching
	    packets before autotuning starts or if autotuning is  disabled  with
	    '-T'.   This  value  should  be  greater than expected RTT (plus any
	    clock offset when not specifying a fixed offset with the -o option).
	    (Default: 60)

     -G     Maximum number of packets that will be searched to match a pair  be-
	    fore giving up (Default: 10000 [pcap file] or 500 [live])

     -P     Enable  pcap/bpf filtering of packets passed into user-space for SPP
	    processing. This filters out any packets not using the specified  IP
	    addresses, and any pcap frames that are not DLT_EN10MB. (Disabled by
	    default.)

     -v     Verbosity Level (Default: 0)
		Determines information that is displayed on the console.
		The verbosity level is the total of the IDs of each required
		detail as listed below:
		    1 Queue Size
		    2 Thread Details
		    4 Pair Info
		    8 Record Info
		    16 Instance Info
		    32 Packet Info
		    64 RTT COUNT - "checksum"
		    128 Network Details
		    1024 Verbose Network Details

     -H     Specify hash function used for packet ID generation, must be "crc32"
	    or "crc64" (default: crc64)

     -T     Disable  the default autotuning of T Delta using actual clock offset
	    estimates

   Source options:
     -f     PCAP-format file of packets previously  captured  at  the  reference
	    point

     -F     PCAP-format file of packets previously captured at the monitor point

     -i     Reference  point live capture interface (Except for when acting as a
	    slave - instead use -I)

     -I     Monitor point live capture interface (Also used for reference  point
	    acting as a slave)

   Network options:
     -l     Length of the timestamp field in bytes [1 - 4] (Default: 2)

     -g     Granularity of timestamps in microseconds (Default: 100)

     -t     Network update timeout - Maximum time in seconds between slave send-
	    ing spp sample frames to the master (Default: 1)

   Output options:
     -p     Output  'Server  Processing Times' (The time between matched packets
	    seen at the monitor point)

     -c     Output 'Pair Count' (Running total of pairs the program  has  gener-
	    ated)

     -m     Calculate timestamps from monitor point clock rather than the refer-
	    ence  point clock (Output timestamps are the average of the packet's
	    timestamps that were combined to make the pair)

     -b     Set the timestamp to the time that the first packet of the pair  was
	    first  seen.  (This  is  useful when comparing spp output to the raw
	    trace files).

     -O     Append 'fake' (uncorrected) OWD in each direction to each RTT  line,
	    [OWDref2mon  OWDmon2ref]. The (unknown) clock offset between REF and
	    MON is not taken into account, so this is only useful to track *rel-
	    ative* changes in OWD, not absolute OWD.

   Packet Matching Options:
     -#     The # option maybe used to set which fields are used in  the  packet
	    matching process (Default: 63).  The value of <code> is the total of
	    all the required field IDs as listed below:

	    IP fields:
	      1 Source Address
	      2 Destination Address
	      4 Protocol
	      8 Identification

	    TCP/UDP fields:
	      16 Source Port
	      32 Destination Port

	    TCP fields:
	      64 Sequence Number
	      128 Acknowledgement Number
	      256 Data offset, flags, window size
	      512 Checksum, urgent pointer
	      8192 Up to 12 bytes of TCP payload (limited by packet length)
	      16384 All TCP Options bytes (if present)

	    UDP Fields:
	      1024 Length, checksum
	      2048 Up to 12 bytes UDP data (limited by packet length)

	    Not UDP/TCP:
	      4096 Up to 20 bytes after IP header (limited by packet length)

	    NOTE: When NAT is use, source and destination IP address fields will
	    automatically be omitted from hashes.

PACKET IDENTIFICATION
     A	crucial  step  in pairing packets is identifying each packet seen at REF
     with the same packet seen at MON (separately in each direction).  SPP  does
     this  by  generating  a per-packet hash across a number of fields in the IP
     header, transport protocol header and/or payload. The '-#' option	controls
     what specific combination of fields are used to generate the hash.

     Reliable  disambiguation  of packets requires hashing over fields that vary
     from one packet to the next, yet are invariant between REF and MON (not al-
     tered by network devices along the path). Some  problematic  scenarios  in-
     clude  NAT  (where IP addresses are not invariant along a path, and TCP/UDP
     ports may also be altered) and TCP sequence number remapping (observed  be-
     ing performed by certain 'security' middleboxes).

     When SPP was first developed, the IP.ID field was often unique for every IP
     packet emitted by a sender, and could be relied on to disambiguate retrans-
     missions of higher later segments. However, RFC 6864 has formalised the no-
     tion that IP.ID need only be unique for fragments of a larger IP packet.

     The  TCP  Option bytes are useful for disambiguating TCP packets (including
     retransmissions) where the underlying connections have negotiated (and cor-
     rectly use) the Time Stamp option. In such cases, retransmissions will  al-
     ways differ by their TSval field.

     If you find spp is generating implausibly high RTTs from time to time (such
     as  when  the hash fails to disambiguate a retransmitted TCP segment at MON
     from its orignal seen at REF), use a custom "-# <hashcode>"  to  hash  over
     additional fields.

     If  you  find  spp is not generating RTT estimates, use a custom "-# <hash-
     code>" to hash over fewer fields. (For example, don't  hash  over	TCP  se-
     quence or acknowledgement numbers if a middle-box is rewriting these fields
     mid-path.	Otherwise  spp	will fail to match a packet seen at REF with the
     same packet seen at MON.)

     Until version 0.3.6 spp used CRC32 as  hash  function.  Since  version  0.4
     CRC64 is used by default to reduce the collision probability. The -H option
     can be used to select CRC32 instead.

CLOCK SYNCHRONISATION
     The  SPP  algorithm  does	not strictly require clocks at REF and MON to be
     synchronised. Nevertheless, this SPP  implementation  applies  a  practical
     limit on how far forward and back in time it searches to match packets cap-
     tured at REF and MON monitoring points. By default, your REF and MON clocks
     ought to be synchronised to within 60 seconds (this can be altered with the
     '-d'  option).  If you find SPP is not generating	estimates, it may be due
     to excessive offset between the REF and MON system clocks.

     If you know that your sources have a fixed time offset, SPP can  take  this
     into account. The known offset can be specified in seconds using the

     In addition, the option '-d' can be used to alter the maximum tolerance (in
     seconds)  for  clocks  that are out of sync. See [2] for more details on 'T
     delta'.

     Note that larger -d values will enable you to calculate  estimates  if  the
     synchronisation  wasn't  ideal, but given that the search window is limited
     with -G this may lead to failed matches due the search window being  filled
     with  old	unmatched packets. Since version 0.4 spp autotunes -d by setting
     it to the estimated clock offset plus an approximately 5 second safety mar-
     gin to make sure no packets are lost for the  matching  process.  Initially
     the tolerance specified by -d will be used but after 20 matched packets au-
     totuning will start to take effect. Autotuning can be disabled with -T.

EXAMPLES
   1. From pcap files
     The  IP  at the reference point is 10.0.0.1 and the IP at the monitor point
     is 10.0.0.2. The files /data/ref.pcap and /data/mon.pcap contain data  cap-
     tured  at the reference and monitor points respectively. Note that the dis-
     play of pair count and server processing times are also enabled:

     spp -f /data/ref.pcap -a 10.0.0.1 -F /data/mon.pcap -A 10.0.0.2 -s -c

   2. Local live capture
     Processing RTT in rear realtime from two local interfaces.  This  would  be
     useful  in  a lab environment when testing equipment or networks. There are
     two local interfaces (em0 and em1) with IP addresses 10.0.1.1 and	10.0.2.1
     respectively. The reference point will be em0 (10.0.1.1).

     spp -i em0 -a 10.0.1.1 -I em1 -A 10.0.2.1

   3. Local/Remote with in band hash transmission
     Processing  RTT  in  near	realtime from a local interface at the reference
     point and remote interface at the monitor	point.	This  example  uses  'in
     band' hash transmission.

     The master is running at the reference point and is capturing on the inter-
     face  em0 (Interface address 10.0.0.1). The slave is running at the monitor
     point, capturing on the bge0 interface (Interface address 10.0.0.2).

     On the master:

     spp -i em0 -a 10.0.0.1 -R 10.0.0.2 -A 10.0.0.2

     On the slave:

     spp -s 10.0.0.1 -a 10.0.0.1 -I bge0 -A 10.0.0.2

   4. Local/Remote with out of band hash transmission
     Processing RTT in near realtime from a local  interface  at  the  reference
     point  and remote interface at the monitor point. This example uses 'out of
     band' hash transmission.

     This is the same as the previous example except that  the	hashes	will  be
     sent  across a separate network to that which is being measured. The inter-
     faces to this network have IP addresses of 192.168.0.1 and  192.168.0.2  at
     the reference and monitor points respectively.

     On the master:

     spp -i em0 -a 10.0.0.1 -R 192.168.0.2 -A 10.0.0.2

     On the slave:

     spp -s 192.168.0.1 -a 10.0.0.1 -I bge0 -A 10.0.0.2

   5. From files with NAT
     The  IP  at the reference point is 10.0.0.1 and the IP at the monitor point
     is 136.0.0.2. The files /data/ref.pcap and /data/mon.pcap contain data cap-
     tured at the reference and monitor points respectively. The reference point
     is behind NAT.  To the outside world, it appears to be 136.0.0.1

     spp -f  /data/ref.pcap  -a  10.0.0.1  -n  136.0.0.1  -F  /data/mon.pcap  -A
     136.0.0.2

BUGS
     Live remote capture has not been tested much and may have bugs.

AUTHOR
     Original  implementation by Amiel Heyde <amiel at swin dot edu dot au> Cen-
     tre for Advanced Internet Architectures, Swinburne University  of	Technol-
     ogy, Melbourne, Australia.

CONTRIBUTORS
     Software  designed  in  collaboration with Grenville Armitage <garmitage at
     swin dot edu dot au> Centre for Advanced Internet Architectures,  Swinburne
     University of Technology, Melbourne, Australia

     Original  implementation  extended  and  revised by David Hayes <dahayes at
     swin dot edu dot au>, Atwin O. Calchand <acalchand at swin dot edu dot au>,
     Christopher Holman, Sebastian Zander <szander at  swin  dot  edu  dot  au>,
     Grenville	Armitage <garmitage at swin dot edu dot au>, Centre for Advanced
     Internet Architectures, Swinburne University of Technology, Melbourne, Aus-
     tralia

REFERENCES
     [1] S. Zander, G. Armitage, T. Nguyen, L. Mark, B. Tyo,  "Minimally  Intru-
     sive Round Trip Time Measurements Using Synthetic Packet-Pairs," CAIA Tech-
     nical    Report	060707A,    July    2006.    http://caia.swin.edu.au/re-
     ports/060707A/CAIA-TR-060707A.pdf

     [2] S. Zander, G. Armitage, "Minimally-Intrusive Frequent Round  Trip  Time
     Measurements    Using    Synthetic   Packet-Pairs	 -   Extended	Report",
     CAIA Technical  Report  130730A,  July  2013.   http://caia.swin.edu.au/re-
     ports/130730A/CAIA-TR-130730A.pdf

SEE ALSO
     pcap(3), tcpdump(8)

FreeBSD 			    NOV 2018				  SPP(1)
home | help