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

FreeBSD Manual Pages

  
 
  

home | help
owfetch(1)		    General Commands Manual		    owfetch(1)

NAME
       owfetch - Client	application to fetch buffered OWAMP session data.

SYNOPSIS
       owfetch [options] servhost [SID savefile]+

DESCRIPTION
       owfetch	is  a  command	line client application	used to	fetch buffered
       OWAMP session data.

       OWAMP one-way latency measurements send packets from a sending host  to
       a  receiving  host.  The	receiving host is the only entity that ends up
       with the	results	of the test. When the owampd daemon is used to setup a
       receiving  endpoint, the	daemon buffers that data. The owfetch applica-
       tion can	be used	to fetch the  buffered	data.  (owping	typically  re-
       trieves this information	immediately upon completion of the test	making
       this unnecessary	in most	cases.)

       owfetch is a simple application that can	be used	to fetch this buffered
       data  from  a owampd process running on servhost	if it was not saved as
       part of the owping execution.

       servhost	can be specified using rfc2396 and  rfc2732  syntax  for  both
       host and	port specification:

       node:port
	      IPv4  syntax  where  node	is either a DNS	name or	a numeric host
	      address string consisting	of a dotted decimal IPv4 address.  The
	      port is an optional port specifier to contact servers running on
	      a	non-default port and can be left off in	most cases.  This syn-
	      tax also works for IPv6 addresses	specified using	DNS names.

       [node]:port
	      IPv6  syntax  where  node	is specified using a numeric IPv6 host
	      address string. The []'s are required only if the	optional  port
	      port specifier is	used.

       The SID (Session	Identifier) is a hex number that uniquely identifies a
       single test session. savefile is	the file in which the data  from  that
       test  session  will  be	saved. Any number of SID savefile pairs	can be
       specified on the	command-line to	download more  than  one  session  per
       command	execution.  The	 SID is	printed	out when a test	session	is re-
       quested by owping, unless output	is suppressed with the -Q option.

       savefile	can be specified as /dev/null on UNIX if there is no desire to
       actually	save the session data.

       If  no  options	are  specified,	owfetch	retrieves the buffered session
       data from servhost, saves the data to the savefile, and prints  summary
       statistics.

       OWAMP  supports three reporting formats.	A textual summary that was de-
       signed to be as similar to the results that ping	produces as  possible.
       A  machine  readable summary format (-M). And finally a raw format that
       prints out the data from	each and every packet in as compact of a  for-
       mat  as possible	(-R).  The textual summary also	allows the information
       from each packet	to be reported using the -v option. The	 default  tex-
       tual summary will be used if neither the	-M or the -R options are spec-
       ified.  It includes:

       SID
	      Session Identifier. This value is	unique for every test session.

       Sent, Lost, Duplicates
	      Number of	packets	that were sent,	lost, and duplicated  as  seen
	      by OWAMP.

       Min Delay, Median Delay,	Max Delay, Error Estimate
	      Minimum, median and maximum delay	seen for sample. Maximum error
	      estimate for the sample. (The median is determined using a  his-
	      togram, so the resolution	of this	value is bounded by the	-b pa-
	      rameter. This can	lead to	misleading results, for	 example,  for
	      very  small  values of latency it	is possible to see a value for
	      the median that is greater than the maximum, but this is	simply
	      due to the resolution of the median measurement.)

       Jitter
	      An estimate of how "stable" the delay samples are. OWAMP reports
	      the the 95th percentile of delay - 50th percentile of delay.

       Additional percentiles
	      If the -a	option is used,	those additional percentiles from  the
	      sample are displayed.

       TTL (hops) information
	      As  a  packet  traverses the network, the	IP TTL field is	decre-
	      mented each time the packet crosses a router. OWAMP has been de-
	      signed  to  collect  the	TTL  information from the packets. The
	      OWAMP sender sets	the TTL	of all outgoing	packets	 to  255.  The
	      OWAMP  receiver  retrieves  the  TTL from	the packet. The	normal
	      textual report uses this information to  report  the  number  of
	      hops  (number  of	 routers)  the packet traversed. The number of
	      distinct values is reported as well as the minimum  and  maximum
	      number  of  hops seen in the given session.  The other reporting
	      formats just report raw TTL values as seen in the	packets.   (It
	      should be	noted that if the number of hops reported seems	unusu-
	      ally large, it probably means the	OWAMP sender was not  able  to
	      set  the	TTL  value correctly. The traceroute(1)	program	can be
	      used to verify what OWAMP	is reporting.)

       Reordering
	      Finally OWAMP reports the	amount of re-ordering it  observed.  A
	      description of the metric	used to	report this can	be found at:
	      http://www.internet2.edu/performance/owamp/draft-shalunov-reordering-definition-02.txt.html

OPTIONS
       -h
	      Print a usage message and	exit.

	      Default:
		     Unset.

   Connection/Authentication Options:
       -4
	      Forces OWAMP clients to use IPv4 addresses only.

	      Default:
		     Unset. OWAMP will use IPv4	or  IPv6  address,  but	 tries
		     IPv6 first.

       -6
	      Forces OWAMP clients to use IPv6 addresses only.

	      Default:
		     Unset.  OWAMP  will  use  IPv4 or IPv6 address, but tries
		     IPv6 first.

       -A authmode
	      Specify the authentication modes the client is  willing  to  use
	      for  communication. authmode should be set as a character	string
	      with any or all of the characters	"AEO". The modes are:

	      A	     [A]uthenticated. This mode	encrypts the  control  connec-
		     tion and digitally	signs part of each test	packet.

	      E	     [E]ncrypted.  This	 mode  encrypts	the control connection
		     and encrypts each test packet in full. This  mode	forces
		     an	 encryption  step  between the fetching	of a timestamp
		     and when the packet is sent. This adds more computational
		     delay to the time reported	by OWAMP for each packet.

	      O	     [O]pen. No	encryption of any kind is done.

	      The client can specify all the modes with	which it is willing to
	      communicate.  The	most strict mode that both  the	 OWAMP	server
	      and  the	OWAMP  client are willing to use will be selected. Au-
	      thenticated and Encrypted	modes require a	"shared	secret"	in the
	      form of a	pass-phrase that is used to generate the AES and HMAC-
	      SHA1 session keys.

	      Default:
		     "AEO".

       -k pfsfile
	      Use the pass-phrase in pfsfile for username to derive  the  sym-
	      metric  AES key used for encryption.  username must have a valid
	      entry in pfsfile.	 pfsfile can be	generated as described in  the
	      pfstore(1) manual	page.

	      Default:
		     Unset.  (If  the  -u option was specified without the -k,
		     the user will be prompted for a passphrase.)

       -S srcaddr
	      Bind the local address of	the client socket to srcaddr.  srcaddr
	      can  be specified	using a	DNS name or using standard textual no-
	      tations for the IP addresses. (IPv6 addresses are	of course sup-
	      ported.)

	      Default:
		     Unspecified (wild-card address selection).

       -u username
	      Specify  the  username  that identifies the shared secret	(pass-
	      phrase) used to derive the AES and HMAC-SHA1  session  keys  for
	      authenticated  and  encrypted  modes. If the -k option is	speci-
	      fied, the	pass-phrase is retrieved from the  pfsfile,  otherwise
	      the user is prompted for a pass-phrase.

	      Default:
		     Unset.

Output Options:
       -a percentile_list
	      percentile_list  indicates  the list of quantiles	to be reported
	      out in addition to median. This is done by specifying a list  of
	      percentiles  in  a  comma	 separated  string (spaces are not al-
	      lowed). Each percentile is indicated by a	floating  point	 value
	      between 0.0 and 100.0.

	      This value is only used if reporting summary statistics.

	      Default:
		     Unset.

       -b bucket_width
	      A	 histogram of delays is	created	to compute the summary statis-
	      tics.  (This is used to compute percentiles of delay such	as me-
	      dian.)  The bucket_width indicates the resolution	of the bins in
	      the histogram. This value	is specified using  a  floating	 point
	      value and	the units are seconds.

	      Because a	histogram to compute the median	(and other percentiles
	      of delay)	the results can	be misleading if the  bucket_width  is
	      not appropriate. For example, if all of the delays in the	sample
	      are smaller than the value of bucket_width then the median  will
	      be  reported  as	bucket_width, a	value that is greater than the
	      maximum delay in the sample. To avoid this, bucket_width	should
	      be  picked to be smaller than (max - min). The default value was
	      selected to be reasonable	for most real network paths, it	is not
	      appropriate for tests to the localhost however.

	      This value is only used if reporting summary statistics.

	      Default:
		     0.0001 (100 usecs)

       -d dir
	      dir  indicates  the  directory in	which to save summary files if
	      the -p option is used.

	      Default:
		     (current working directory)

       -M
	      Print summary information	in a more computer  pars-able  format.
	      Specifically, values are printed out in a	key/value style. Units
	      are seconds for all time values.

	      The -M option is ignored if -Q is	set.

	      Default:
		     Unset.

       -N count
	      Number of	test packets to	put in sub-session summaries when com-
	      puting statistics	on owamp session data.

	      This  option  is	used  to  break	down the summary statistics in
	      smaller sample sizes than	a complete owp file.  This  is	useful
	      when breaking up very long running sessions.

	      This  option  is only used for statistical output, and therefore
	      has no effect on the -R output mode.

	      Default:
		     Unset. (complete files are	treated	as the sample size)

       -n units
	      units indicates what units time values should  be	 reported  in.
	      units is specified using a single	character specifying the units
	      wanted.

	      The available units are:

	      'n'   nanoseconds	(ns)
	      'u'   microseconds (us)
	      'm'   milliseconds (ms)
	      's'   seconds (s)

	      This is only used	for the	human-readable summary statistics  and
	      the  -v  mode of reporting individual records. In	particular, it
	      is not used for the -R or	-M output modes.

	      Default:
		     Unset.

       -p
	      Save output summary information into files instead  of  printing
	      it  to STDOUT. Also, print the names of the files	to STDOUT. The
	      files will be saved in the directory specified by	the -d option.

	      The summary filenames are	in the format:

	      ${START_TIME}_${END_TIME}.${FILETYPE}

	      STARTTIME	and ENDTIME are	the start and end timestamps  for  the
	      session  or sub-session. The timestamps are ASCII	representation
	      of 64 bit	integers with the high-order 32	bits representing  the
	      number  of  seconds  since Jan 1,	1900 and the low-order 32 bits
	      representing fractional seconds.	The FILETYPE  is  sum  for  -M
	      summary  files,  and  txt	for the	default	human-readable summary
	      information.

	      This option is ignored if	the -R option is specified.

	      Default:
		     Unset.

       -Q
	      Suppress the printing of all summary statistics and  human-read-
	      able individual delays (-v).

	      Default:
		     Unset.

       -R
	      Print individual packet records one per line in the raw format:

	      SEQNO SENDTIME SSYNC SERR	RECVTIME RSYNC RERR TTL

	      SEQNO	 Sequence number.
	      SENDTIME	 Send timestamp.
	      SSYNC	 Sending system	synchronized (0	or 1).
	      SERR	 Estimate of SENDTIME error.
	      RECVTIME	 Receive timestamp.
	      RSYNC	 Receiving system synchronized (0 or 1).
	      RERR	 Estimate of RECVTIME error.
	      TTL	 TTL IP	field.

	      The  timestamps are ASCII	representation of 64 bit integers with
	      the high-order 32	bits representing the number of	seconds	 since
	      Jan  1,  1900  and the low-order 32 bits representing fractional
	      seconds.	Lost packet records are	indicated with a RECVTIME of 0
	      (zero).  The sequence number is simply an	integer. The error es-
	      timates are printed as floating-point numbers  using  scientific
	      notation.	TTL is the IP field from the packet.  The TTL in send-
	      ing packets should be initialized	to 255,	so the number of  hops
	      the  packet  traversed can be computed. If the receiving host is
	      not able to determine the	TTL field, this	will  be  reported  as
	      255. (Some socket	API's do not expose the	TTL field.)

	      The -R option implies -Q.

	      Default:
		     Unset.

       -v
	      Print  delays for	individual packet records. This	option is dis-
	      abled by the -Q and -R options.

	      Default:
		     Unset.

EXAMPLES
       owfetch somehost.com abcdef0123456789abcdef0123456789 save.owp

	      Contact host somehost.com. Fetch the test	session	identified  by
	      the  SID abcdef0123456789abcdef0123456789. Print summary statis-
	      tics on that file	and save the data in save.owp.

       owfetch -R somehost.com abcdef0123456789abcdef0123456789	save.owp

	      Contact host somehost.com. Fetch the test	session	identified  by
	      the SID abcdef0123456789abcdef0123456789.	Print the raw decoding
	      of the data in that file and save	the session data in save.owp.

       owfetch -M somehost.com abcdef0123456789abcdef0123456789	save.owp

	      Contact host somehost.com. Fetch the test	session	identified  by
	      the  SID	abcdef0123456789abcdef0123456789.  Print  the  machine
	      pars-able	summary	statistics for that session and	save the  ses-
	      sion data	in save.owp.

       owfetch -v somehost.com abcdef0123456789abcdef0123456789	save.owp

	      Contact  host somehost.com. Fetch	the test session identified by
	      the SID abcdef0123456789abcdef0123456789.	Print  individual  de-
	      lays for each packet in human readable format. Print the summary
	      statistics.  Save	the session data in save.owp.

       owfetch	-U  someuser   somehost.com   abcdef0123456789abcdef0123456789
       save.owp

	      The  same	 action	 as the	first example.	Authenticate using the
	      identity someuser. owfetch will prompt for a passphrase.

SEE ALSO
       owampd(8),    owping(1),	   owstats(1),	  aespasswd(1)	   and	   the
       http://e2epi.internet2.edu/owamp/ web site.

ACKNOWLEDGMENTS
       This  material  is based	in part	on work	supported by the National Sci-
       ence Foundation (NSF) under Grant No. ANI-0314723. Any opinions,	 find-
       ings  and conclusions or	recommendations	expressed in this material are
       those of	the author(s) and do not necessarily reflect the views of  the
       NSF.

	     $Date: 2007-03-06 17:02:45	-0500 (Tue, 06 Mar 2007) $  owfetch(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | Output Options: | EXAMPLES | SEE ALSO | ACKNOWLEDGMENTS

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

home | help