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 measurements. 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 continuous 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 communication. (We really want to see periods of time where the network is broken.) Therefore, it is important to create fairly long OWAMP test sessions. 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 summary 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 information 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 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 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 subdivided to provide intermediate results.

powstream produces data in two formats: raw owamp data files and summary 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 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)

-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 summary 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 approximately 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 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: Indicates that powstream should 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 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 specified, 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 indicates the resolution of the bins in the histogram. This value is specified using a floating point value and the units are seconds.
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 powstream output sub-session summary files at shorter periods. The data should be considered preliminary because it is being generated before the actual end of the test session. The OWAMP control protocol shares information from the sending process to the receiver about any packets it skipped sending when the test session ends. Because this data is being generated before the session 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 packets 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 complete 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.

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.