owping
Section: User Commands (1)
Updated: $Date: 2009-01-12 09:46:23 -0500 (Mon, 12 Jan 2009) $
Index
Return to Main Contents
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
measurements. 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 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.
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 packets.
(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
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.
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 |
DF |
CS0 |
|
CS1 | 001000 | Low-Priority Data | No BW assurance
|
|
AF11 | 001010 | High-Throughput Data | Store and forward
|
AF12 | 001100 |
AF13 | 001110 |
|
CS2 | 010000 | OAM | OAM&P
|
|
AF21 | 010010 | Low-Latency Data | Web-based ordering
|
AF22 | 010100 |
AF23 | 010110 |
|
CS3 | 011000 | Broadcast Video | TV & live events
|
|
AF31 | 011010 | Multimedia Streaming | Streaming video and audio
|
AF32 | 011100 |
AF33 | 011110 |
|
CS4 | 100000 | Real-Time Interactive | Video conf and gaming
|
|
AF41 | 100010 | Multimedia Conferencing | H.323 video conferencing
|
AF42 | 100100 |
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 bidirectional tests, otherwise only the explicit directions are
performed.
-
- Default:
-
True, unless the -t or -T have been specified explicitly.
- -i send_schedule
-
send_schedule
indicates the scheduled delay between sent packets. This is done by
specifying a list of delays in a comma separated 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 enddelay
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 specified.
-
- Default:
-
2 seconds longer than the round-trip estimate. (seconds)
- -P 0 | lowport-highport
-
Specify the specific port range to use on the local host 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
size for a test packet in open mode is 14 bytes. The minimal size
for a test packet in authenticated or encrypted mode is 32 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 bidirectional tests, otherwise only the explicit directions are
performed.
-
- Default:
-
True, unless the -f or -F have been specified explicitly.
- -z delayStart
-
Time to wait before starting a test. owping attempts to calculate 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:
- -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.
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 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.
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 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
-
- Test Configuration Options:
-
- Connection/Authentication Options:
-
- Output Options:
-
- ENVIRONMENT VARIABLES
-
- EXAMPLES
-
- SEE ALSO
-
- ACKNOWLEDGMENTS
-
This document was created by
man2html,
using the manual pages.
Time: 17:52:42 GMT, January 23, 2009