FreeBSD Manual Pages
powstream(1) General Commands Manual 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 al- low for continuous monitoring of one-way latencies. To create a contin- uous 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 in- dicated 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 avail- able 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 informa- tion about any packet records that the sender did not send; therefore, the preliminary data could show packet loss when, in reality, the send- ing 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 de- claring 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 in- tervals 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. Au- thenticated 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 no- tations 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: 2009-01-12 09:46:23 -0500 (Mon, 12 Jan 2009) $powstream(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | EXAMPLES | SEE ALSO | ACKNOWLEDGMENTS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=powstream&sektion=1&manpath=FreeBSD+Ports+15.0>