owping(1) 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
parameters 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
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
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 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.
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
receiver. 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
indicate 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
delayStart is specified as a value less than this reasonable
minimum 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.
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.
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
every 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
owping.
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$ owping(1)
