owfetch(1)owfetch(1)NAMEowfetch - Client application to fetch buffered OWAMP session data.
SYNOPSISowfetch [options] servhost [SID savefile]+
DESCRIPTIONowfetch 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.
EXAMPLESowfetch 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 ALSOowampd(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)
