FreeBSD Manual Pages

home | help

owping(1) General Commands Manual 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 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 ad-
dress 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 ad-
dress 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 speci-
fied using the same syntax as the testpeer.

The owping client is used to request the type of test wanted. The parame-
ters 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 re-
ported 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 es-
timate 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
the 95th percentile of delay - 50th percentile of delay.

Additional percentiles
If the -a option is used, those additional percentiles from the sam-
ple 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 infor-
mation 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 de-
scription 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 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 dis-
tributed pseudo-random quantity with a mean about the value
given. (This is the default if no alpha qualifier is speci-
fied. 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 mes-
sage.

This is important if the sender clock is running ahead of the re-
ceiver 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 num-
ber 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 du-
plicate packets. I.e., add this number to the duration of your ses-
sion 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 for OWAMP-Test packets. This
can be specified in two ways. First, as 0 which would indicate ow-
ping 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 authenticated 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 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 hap-
pens after completion of the setup protocol. If delayStart is speci-
fied as a value less than this reasonable minimum delay, the reason-
able 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 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 en-
cryption 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 per-
centiles 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 ap-
propriate. For example, if all of the delays in the sample are
smaller than the value of bucket_width then the median will be re-
ported as bucket_width, a value that is greater than the maximum de-
lay 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 comput-
ing 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 ses-
sion 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 ex-
pose 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 some-
host.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 re-
ceived 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

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 some-
host.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 some-
host.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.

$Date: 2009-01-12 09:46:23 -0500 (Mon, 12 Jan 2009) $ owping(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=owping&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages