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

FreeBSD Manual Pages

  
 
  

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

NAME
       owping -	Client application to request one-way latency tests.

SYNOPSIS
       owping [options]	testpeer [server]

DESCRIPTION
       owping  is  a  command line client application that is used to initiate
       one-way latency tests.

       Round-trip latency measurements (ping) are  an  accepted	 technique  to
       look  for  network problems; One-way measurements have the potential to
       be even more useful. With round-trip measurements it  is	 difficult  to
       isolate	the  direction in which	congestion is experienced.  Traffic is
       often asymmetric	with many sites	being either  primarily	 producers  or
       consumers of data. One-way measurements allow more informative measure-
       ments. It is much easier	to isolate the effects of traffic on  specific
       parts of	a network.

       owping  works  by  contacting an	owampd daemon on the remote peer host.
       owampd manages the resources of the host	on which it runs.

       testpeer	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.

       server  is an optional argument that indicates the OWAMP	server address
       if it is	different from the testpeer. This is mostly useful in the case
       of hosts	with more than one network interface where the OWAMP server is
       not listening on	the interface that you want to test.  The  server  can
       be specified using the same syntax as the testpeer.

       The  owping  client is used to request the type of test wanted. The pa-
       rameters	allow the user to select the full send schedule, direction  of
       test  (send, receive, or	both) as well as packet	size.  The results are
       returned	to the client after the	test completes.	The test will  not  be
       complete	until timeout after the	last packet is scheduled to be sent.

       With no options specified, owping will perform concurrent bidirectional
       tests of	100 packets each at a rate of approximately 1 packet every 0.1
       seconds to and from the testpeer. Then, the receivers on	each host will
       wait a reasonable period	after that to count possible  duplicate	 pack-
       ets.   (See  the	 -L  option.) Upon completion of the sessions, summary
       statistics are printed to STDOUT.

       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.

   Test	Configuration Options:
       -c count
	      Number of	test packets to	send in	the test session.

	      Default:
		     100

       -D DSCP
	      Set an RFC 2474 style DSCP value for the TOS byte	in the sending
	      packets. This can	be set using a 6-bit numeric value in decimal,
	      hex,  or octal. Additionally, the	following set of symbolic DSCP
	      name constants are understood. (Example applications  are	 taken
	      from RFC 4594.)

       +--------+--------+-------------------------+---------------------------+
       | Name	| Value	 |	Service	Class	   |	     Examples	       |
       +--------+--------+-------------------------+---------------------------+
       |NONE	|	 |			   |			       |
       |DEFAULT	| 000000 |	  Standard	   |	 Undifferentiated      |
       |DF	|	 |			   |			       |
       |CS0	|	 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
       |CS1	| 001000 |    Low-Priority Data	   |	  No BW	assurance      |
       +--------+--------+-------------------------+---------------------------+
       |AF11	| 001010 |			   |			       |
       |AF12	| 001100 |  High-Throughput Data   |	 Store and forward     |
       |AF13	| 001110 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
       |CS2	| 010000 |	     OAM	   |	       OAM&P	       |
       +--------+--------+-------------------------+---------------------------+
       |AF21	| 010010 |			   |			       |
       |AF22	| 010100 |    Low-Latency Data	   |	Web-based ordering     |
       |AF23	| 010110 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
       |CS3	| 011000 |     Broadcast Video	   |	 TV & live events      |
       +--------+--------+-------------------------+---------------------------+
       |AF31	| 011010 |			   |			       |
       |AF32	| 011100 |  Multimedia Streaming   | Streaming video and audio |
       |AF33	| 011110 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
       |CS4	| 100000 |  Real-Time Interactive  |   Video conf and gaming   |
       +--------+--------+-------------------------+---------------------------+
       |AF41	| 100010 |			   |			       |
       |AF42	| 100100 | Multimedia Conferencing | H.323 video conferencing  |
       |AF43	| 100110 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
       |CS5	| 101000 |	  Signaling	   |   Video conf and gaming   |
       +--------+--------+-------------------------+---------------------------+
       |EF	| 101110 |	  Telephony	   |	IP Telephony bearer    |
       +--------+--------+-------------------------+---------------------------+
       |CS6	| 110000 |     Network Control	   |	  Network routing      |
       +--------+--------+-------------------------+---------------------------+
       |CS7	| 111000 |			   |			       |
       +--------+--------+-------------------------+---------------------------+
	      Default:
		     Unset.

       -f | -F fromfile
	      Perform  a One-way test from the target testpeer.	The -F form is
	      used to save the results in fromfile. If no directional  options
	      (-f, -F, -t, -T) are specified, owping requests concurrent bidi-
	      rectional	tests, otherwise only the explicit directions are per-
	      formed.

	      Default:
		     True, unless the -t or -T have been specified explicitly.

       -i send_schedule
	      send_schedule  indicates	the scheduled delay between sent pack-
	      ets. This	is done	by specifying a	list of	delays in a comma sep-
	      arated  string (spaces are not allowed). Each delay is indicated
	      by a value and a type. There are two currently  available	 types
	      of delays	that can be specified:

	      f	     [f]ixed  offsets. This is used to indicate	that the value
		     is	a real offset.

	      e	     [e]xponential. This is used to indicate an	 exponentially
		     distributed  pseudo-random	quantity with a	mean about the
		     value given. (This	is the default if no  alpha  qualifier
		     is	specified. The intent of this is to negate periodicity
		     effects.)

	      When the sending process starts, it looks	at the first delay  in
	      the  list	and waits that long to send the	first packet. It takes
	      the next delay from the list to determine	 how  much  longer  to
	      wait  before  sending  the second	packet.	This process continues
	      until there are no more delay values specified in	the  list.  At
	      this  point  the	sending	process	loops back to the beginning of
	      the complete send_schedule and this process begins  again.  This
	      continues	 until	the  sending process has sent count packets as
	      specified	by the -c option.

	      Default:
		     0.1e (seconds)

       -E enddelay
	      Amount of	time for a sender to  wait  after  session  completion
	      (last  packet  send-time	plus  timeout) before sending the stop
	      sessions message.

	      This is important	if the sender clock is running	ahead  of  the
	      receiver clock.

	      A	 session  is complete timeout after the	send time of the final
	      packet.  If the sender clock is ahead of	the  receivers	clock,
	      the  sender  will	 declare  the  session complete	before the re-
	      ceiver. The receiver is only allowed to retain records  for  the
	      packets  that  were sent at least	timeout	before it receives the
	      stop sessions message from the sender. Therefore,	if the	sender
	      clock  is	running	ahead of the receiver clock, the receiver will
	      be forced	to delete some number of the final  packets  from  the
	      session.

	      This parameter directs the sender	to wait	enddelay after session
	      completion allowing the receiver clock to	be essentially	endde-
	      lay later	than the sender	clock and still	retain full sessions.

	      Default:
		     1.0 (seconds)

       -L timeout
	      Amount  of  time	to  wait  for  a  packet to be received	before
	      declaring	it lost. As such, it is	also the amount	 of  time  the
	      test session has to stay active after the	last packet is sent to
	      be able to count duplicate packets. I.e.,	add this number	to the
	      duration	of your	session	to determine how long to expect	a test
	      session to take.

	      Note: The	default	of 2 seconds longer than a round-trip estimate
	      was  simply a guess for how long a typical user would be willing
	      to wait after the	end of the test	for the	results. For the OWAMP
	      results  to  be statistically relevant and to be able to compare
	      data between two sessions	the timeout option  should  be	speci-
	      fied.

	      Default:
		     2 seconds longer than the round-trip estimate. (seconds)

       -P 0 | lowport-highport
	      Specify  the  specific port range	to use for OWAMP-Test packets.
	      This can be specified in two ways. First,	as 0 which would indi-
	      cate   owping   should   allow  the  system  to  pick  the  port
	      (ephemeral). Second, as a	range.	 lowport  must	be  a  smaller
	      value  than highport and both numbers must be valid port values.
	      (16 bit unsigned integer values)

	      Default:
		     0

       -s size
	      Size of the padding to add to each minimally-sized test  packet.
	      The  minimal  UDP	 payload  for a	test packet in open mode is 14
	      bytes. The minimal UDP payload for a test	 packet	 in  authenti-
	      cated or encrypted mode is 48 bytes.

	      Default:
		     0 (bytes)

       -t | -T tofile
	      Perform  a  one-way test toward the target testpeer. The -T form
	      is used to save the results in tofile. If	no directional options
	      (-f, -F, -t, -T) are specified, owping requests concurrent bidi-
	      rectional	tests, otherwise only the explicit directions are per-
	      formed.

	      Default:
		     True, unless the -f or -F have been specified explicitly.

       -z delayStart
	      Time  to	wait before starting a test. owping attempts to	calcu-
	      late a reasonable	minimum	delay to ensure	that the start of  the
	      test  happens  after  completion	of  the	setup protocol.	If de-
	      layStart is specified as a value less than this reasonable mini-
	      mum delay, the reasonable	minimum	will be	used instead.

	      Default:
		     2-3 times the round-trip estimate plus 1 (seconds)

   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.

ENVIRONMENT VARIABLES
       OWAMP Environment Variable   Description
       ----------------------------------------------------------------

       OWAMP_DEBUG_TIMEOFFSET	    Offset time	by this	amount (float)

EXAMPLES
       owping somehost.com

	      Run  two	concurrent  ~10-second	test  sessions	at a rate of a
	      packet every 0.1 seconds.	One session sending packets  from  the
	      local  host to somehost.com, the other session receiving packets
	      from somehost.com.) Print	 summary  statistics  of  the  results
	      only.

       owping somehost.com:98765

	      Run the same two concurrent test sessions	to a server running on
	      somehost.com but on a non-default	port.

       owping -u someuser somehost.com

	      Run the default test as in the first example. Authenticate using
	      the identity someuser. owping will prompt	for a passphrase.

       owping -f somehost.com

	      Run a single ~10-second test session at a	rate of	one packet ev-
	      ery 0.1 seconds with the packets being  sent  from  somehost.com
	      and received at the local	host.

       owping -F from.owp somehost.com

	      Same  as	the previous example, with the resulting data saved in
	      from.owp.	The  owstats  program  can  be	used  to  decode  that
	      datafile using the same Output options that are available	in ow-
	      ping.

       owping -F from.owp -T to.owp somehost.com

	      Run two concurrent ~10-second test  sessions  at	a  rate	 of  a
	      packet  every  0.1 seconds. One session sending packets from the
	      local host to somehost.com, the other session receiving  packets
	      from  somehost.com.) Print summary statistics of the results and
	      save the resulting data saved in from.owp	and to.owp.

       owping -i 1e -c 10 somehost.com

	      Run two concurrent ~10-second test sessions at an	 average  rate
	      of  1  packet every second. One session sending packets from the
	      local host to somehost.com, the other session receiving  packets
	      from  somehost.com.)   Print  summary  statistics	of the results
	      only.

       owping -i 1f -c 10 somehost.com

	      Run two concurrent ~10-second test  sessions  at	a  rate	 of  1
	      packet  every second. One	session	sending	packets	from the local
	      host to somehost.com, the	other session receiving	 packets  from
	      somehost.com.)  Print summary statistics of the results only.

       owping -i 1.0e,0f -c 20 somehost.com

	      Run  two	concurrent ~10-second test sessions. Send back-to-back
	      packet pairs at an average rate of a packet pair	every  1  sec-
	      onds.   One session sending packets from the local host to some-
	      host.com,	 the  other  session  receiving	 packets  from	 some-
	      host.com.)  Print	summary	statistics of the results only.

SEE ALSO
       owampd(8),	  owstats(1),	      owfetch(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: 2009-01-12 09:46:23	-0500 (Mon, 12 Jan 2009) $   owping(1)

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

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

home | help