Internet2

One-Way Ping (OWAMP)

About     |     Downloads      |     Manual Pages     |     Cookbook (PDF)     |     License

owfetch(1)                                                          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
       retrieves this information immediately upon completion of the test mak-
       ing 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
       requested 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
       designed to be as similar to the results that ping produces  as  possi-
       ble.  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
       format  as possible (-R).  The textual summary also allows the informa-
       tion from each packet to be reported using the -v option.  The  default
       textual  summary  will  be used if neither the -M or the -R options are
       specified.  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
              parameter. 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
              designed 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.
              Authenticated  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
              notations  for  the  IP addresses. (IPv6 addresses are of course
              supported.)

              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
              allowed). 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
              median.) 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
              estimates 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
              delays for each packet in human readable format. Print the  sum-
              mary 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$                          owfetch(1)