Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

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

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
       updated	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 experienced by any application's	traffic	without	needing	 modi-
       fications 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  con-
       sidered	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  travelling	 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	inter-
       faces 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
	      before 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 spec-
	      ified 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
	      sending spp sample frames	to the master (Default:	1)

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

       -c     Output 'Pair Count' (Running total of pairs the program has gen-
	      erated)

       -m     Calculate	timestamps from	monitor	point clock  rather  than  the
	      reference	 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 be-
	      tween REF	and MON	is not taken into account,  so	this  is  only
	      useful to	track *relative* 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	gener-
       ate 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  altered by	network	devices	along the path). Some problematic sce-
       narios include NAT (where IP addresses are not invariant	along a	 path,
       and  TCP/UDP  ports may also be altered)	and TCP	sequence number	remap-
       ping (observed being performed by certain 'security' middleboxes).

       When SPP	was first developed, the IP.ID field was often unique for  ev-
       ery  IP	packet	emitted	 by a sender, and could	be relied on to	disam-
       biguate retransmissions of higher later segments. However, RFC 6864 has
       formalised the notion that IP.ID	need only be unique for	fragments of a
       larger IP packet.

       The TCP Option bytes are	useful for disambiguating TCP packets (includ-
       ing  retransmissions)  where the	underlying connections have negotiated
       (and correctly use) the Time Stamp option. In such  cases,  retransmis-
       sions will always 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  seg-
       ment 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  "-#
       <hashcode>"  to	hash  over fewer fields. (For example, don't hash over
       TCP sequence 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
       captured	at REF and MON monitoring points. By default, your REF and MON
       clocks ought to be synchronised to within 60 seconds (this can  be  al-
       tered  with  the	'-d' option). If you find SPP is not generating	 esti-
       mates, 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	 auto-
       tunes  -d  by setting it	to the estimated clock offset plus an approxi-
       mately 5	second safety margin 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 autotuning will start to take effect.  Au-
       totuning	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  captured  at  the reference and monitor points respectively. Note
       that the	display	of pair	count and server processing times are also en-
       abled:

       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
       interface 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 in-
       terfaces	  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 captured 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>
       Centre for Advanced Internet  Architectures,  Swinburne	University  of
       Technology, 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, Australia

REFERENCES
       [1] S. Zander, G. Armitage, T. Nguyen, L. Mark, B. Tyo, "Minimally  In-
       trusive	Round  Trip  Time  Measurements	Using Synthetic	Packet-Pairs,"
       CAIA Technical 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PACKET IDENTIFICATION | CLOCK SYNCHRONISATION | EXAMPLES | BUGS | AUTHOR | CONTRIBUTORS | REFERENCES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=spp&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help