owfetch
Section: User Commands (1)
Updated: $Date: 2007-03-06 17:02:45 -0500 (Tue, 06 Mar 2007) $
Index
Return to Main Contents
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 application can be used to fetch the
buffered data. (owping typically retrieves 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 syntax 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
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 format as possible (-R).
The textual summary also allows the information 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 histogram, 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 interquartile range for this. (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 decremented 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 unusually
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/~shalunov/ippm/draft-shalunov-reordering-definition-02.txt
OPTIONS
- -h
-
Print a usage message and exit.
-
- Default:
-
Unset.
Connection/Authentication Options:
- -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 connection 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 symmetric 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 specified,
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 statistics.
(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 computing
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-readable 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 sending 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 disabled 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 statistics 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 session 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 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 Science
Foundation (NSF) under Grant No. ANI-0314723. Any opinions, findings and
conclusions or recommendations expressed in this material are those of
the author(s) and do not necessarily reflect the views of the NSF.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- Connection/Authentication Options:
-
- Output Options:
-
- EXAMPLES
-
- SEE ALSO
-
- ACKNOWLEDGMENTS
-
This document was created by
man2html,
using the manual pages.
Time: 17:52:42 GMT, January 23, 2009