powstream(1) powstream(1)
NAME
powstream - Client daemon application for continuous one-way latency
tests.
SYNOPSIS
powstream [options] testpeer [server]
DESCRIPTION
powstream is a command line client daemon application that is used to
initiate a continuous stream of one-way latency tests from the testpeer
to the client host.
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.
powstream creates a continuous stream of one-way packet samples by
stitching together multiple OWAMP test sessions. It was designed to
allow for continuous monitoring of one-way latencies. To create a con-
tinuous stream of packets, powstream actually opens two control sockets
to the server and, effectively, double-buffers OWAMP test sessions. The
start-time of each subsequent session is defined by the computed send
time of the last packet in the previous session.
There are special considerations for this type of application that do
not exist for the owping application. Specifically, it is important to
reduce the amount of control communication that occurs to minimize any
session resets that could occur due to breakdowns in control communica-
tion. (We really want to see periods of time where the network is bro-
ken.) Therefore, it is important to create fairly long OWAMP test ses-
sions. On the other hand, it is nice to get fairly immediate feedback
if there is packet loss. To facilitate this, powstream can summarize
data for smaller time periods than the actual test session periods it
uses. The -N option is used to indicate how many packet records should
be in these smaller sub-session files while the -c option is used to
indicate how many packet records should be in the complete session.
powstream outputs a data file and a summary file for each time period
defined by the -c option. The files will be placed in the directory
indicated by the -d option. Additionally, powstream will output a sum-
mary file for each time period defined by the -N option. The smaller
summary sub-session files should be thought of as preliminary data.
The later, larger complete session files will have additional informa-
tion available to determine the validity of the data. Specifically the
larger file is created after the Stop-Sessions message has been
received from the sender host over the control socket. This message
includes information about any packet records that the sender did not
send; therefore, the preliminary data could show packet loss when, in
reality, the sending process never sent the expected packets.
powstream saves data files and summary files for each session in the
current directory, or the directory specified by the -d option. The
filesnames 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 inte-
gers 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 owp for raw data files and sum for textual
summary files.
powstream 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 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 powstream client-daemon is used to request the intensity of the
test. Specifically, the parameters allow the user to select the mean
packet interval for a pseudo-exponential distribution, the packet size,
and the loss timeout.
With no options specified, powstream will perform tests of 300 packets
each at a rate of approximately 1 packet every 0.1 seconds from the
testpeer. With no options specified, the test sessions will not be sub-
divided to provide intermediate results.
powstream produces data in two formats: raw owamp data files and sum-
mary statistics. The data files are the same binary format saved from
owping and can be parsed using owstats. The summary files are identical
to the -M output format from owstats.
OPTIONS
-h
Print a usage message and exit.
Default:
Unset.
Test Configuration Options:
-c count
Number of test packets to send in each test session.
Default:
300
-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 receiver 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 ses-
sions 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)
-i meanwait
meanwait indicates the average time to wait between sending
packets. powstream uses an exponentially distributed pseudo-
random distribution with a mean interval about the value given.
The intent of this is to negate periodicity effects.
Default:
0.1 (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.
For the OWAMP results to be statistically relevant the timeout
option should be specified the same for comparable sessions.
Default:
10 seconds
-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
Indicates that powstream should set up sender-side OWAMP test
sessions instead of the default receiver-side sessions. This
mode of operation is more problematic because intermediate sum-
mary data must be fetched from the remote server on regular
intervals using an additional socket connection instead of just
summarizing portions of a local data file.
Default:
unset
-z delayStart
Time to wait before starting the test. powstream waits approxi-
mately 10 seconds before starting the first test by default. The
delayStart value is added to this amount.
Default:
0
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 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
Indicates that powstream should use the pass-phrase in pfsfile
for username to derive the symmetric AES key used for encryp-
tion. 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 pass-phrase.)
-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 is used to identify 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 spec-
ified, the pass-phrase is retrieved from the pfsfile otherwise
powstream prompts the user for a pass-phrase.
Default:
Unset
Output Options:
-b bucket_width
To reasonably compute the delay summary statistics, powstream
creates a histogram of the delays. (This can be used to compute
percentiles of delay, such as median.) The bucket_width indi-
cates the resolution of the bins in the histogram. This value is
specified using a floating point value and the units are sec-
onds.
The histogram is presented within the summary statistics file.
Default:
0.0001 (100 usecs)
-d dir
dir indicates the directory in which to save all raw owp data
files and all textual summary data files.
Default:
(current working directory)
-e facility
facility indicates the syslog facility to which powstream should
send all error messages.
Default:
LOG_USER
-N count
Number of test packets to put in sub-session summary files.
powstream can use large session durations to minimize control
communication during execution. This option is used to make pow-
stream output sub-session summary files at shorter periods. The
data should be considered preliminary because it is being gener-
ated before the actual end of the test session. The OWAMP con-
trol protocol shares information from the sending process to the
receiver about any packets it skipped sending when the test ses-
sion ends. Because this data is being generated before the ses-
sion actually ends, any packets the sending process did not get
a chance to send will show up as lost packet records in these
files.
This is the trade-off for getting more immediate access to the
data.
If this option is not set, then sub-session summary files will
not be produced.
This value must be a divisor of the value specified for the -c
option.
Default:
unset
-p
Print the names of data files and summary statistic files to
STDOUT when they are completed.
Default:
unset
-R
Suppress printing error messages to STDERR. They will still be
sent to syslog.
Default:
unset (errors print to STDERR and syslog)
-v
Print more verbose information in error messages.
Default:
unset
ENVIRONMENT VARIABLES
OWAMP Environment Variable Description
----------------------------------------------------------------
OWAMP_DEBUG_TIMEOFFSET Offset time by this amount (float)
EXAMPLES
powstream somehost.com
Contact somehost.com and request ongoing tests with a sending
rate of a packet approximately every 0.1 seconds, with 300 pack-
ets per session. (Each session will last about 30 seconds.) Save
the data and summary files in the current directory.
powstream -L 10 -i 1 -c 10800 -N 30 -d datadir -p somehost.com
Contact somehost.com and request ongoing tests. Use a timeout
duration of 10 seconds. Tests will have a sending rate of a
packet approximately every 1 second, with 10800 packets per com-
plete session. (Each session will last about 3 hours.) Create
sub-session summary statistic files, as well, with 30 packets
per sub-session. (Each sub-session will provide a sample period
of about 30 seconds.) Save the data and summary files in the
current directory and print each filename as it is produced.
SEE ALSO
owampd(8), owping(1), 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$ powstream(1)
