table of contents
bwctl(1) | General Commands Manual | bwctl(1) |
NAME¶
bwctl - Client application to request throughput tests.SYNOPSIS¶
bwctl [ options] -c recvhost -s sendhostDESCRIPTION¶
bwctl is a command line client application that is used to initiate throughput tests.- This version of bwctl is capable of initiating Iperf, Nuttcp, and Thrulay tests.
ARGUMENTS¶
Connection/Authentication Arguments:¶
- -4
- Forces bwctl to use IPv4 addresses only.
- Default:
- Unspecified (IPv6 is preferred).
- -6
- Forces bwctl to use IPv6 addresses only.
- Default:
- Unspecified (IPv6 is preferred).
- -A authmethod
- authmethod is used to specify the authentication method the bwctl client is willing to use for communication with the bwctld on the sendhost and recvhost. The authentication options of bwctl are intended to be extensible. The communication from the bwctl client to each bwctld server may take different options for different types of authentication. If the authmethod option is specified for either the -s, or the -c argument, it overrides the authmethod specified with the -A option for communication with that particular host. (Therefore, the -A argument is really only useful if the same authentication can be used with both hosts.)
Allowing different authentication methods for each connection should allow a
client to use different authentication methods with different servers which
should in turn allow cross-domain tests to occur more easily.
The format for authmethod is:
authmode [authscheme schemeopts]
authscheme and schemeopts are only needed if authenticated
communication ( A or E modes of authmode) is wanted with
sendhost and recvhost.
- authmode
- Specifies the authentication mode the client is willing to speak with a server. It must 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.
- E
- [E]ncrypted. This mode encrypts the control connection. If the test supports encryption, this mode will additionally encrypt the test stream. (Encryption of the test stream is not currently supported, so this mode is currently identical to authenticated.)
- O
- [O]pen. No encryption of any kind is done.
- Default:
- "AEO"
- authscheme schemeopts
- authscheme indicates the authentication scheme that should be used to achieve the authenticated or encrypted modes. schemeopts are a list of arguments specific to each particular authentication scheme. Supported authscheme values follow (listed with the schemeopts each scheme requires):
- AESKEY userid [keyfile]
- This is the initial "simple" shared secret (AES key) model. userid is required to identify which shared secret the server and client should use. keyfile optionally specifies a file to retrieve the AES key from. If keyfile is not specified, the user will be prompted for a passphrase. keyfile can be generated using the aespasswd(1) application.
- Default:
- Unauthenticated
- -B 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.
- Default:
- Unspecified (wild-card address selection).
- -c recvhost[:port] [authmethod]
- Specifies the host that will run the Iperf, Thrulay or Nuttcp server. The :port suffix is optional and is only needed if bwctld is being run on a non-default port number. If an IPv6 address is being specified, note that the accepted format contains the recvhost portion of the specification in square brackets as: [fe80::fe9f:62d8]:4823. This ensures the port number is distinct from the address specification, and is not needed if the :port suffix is not being used.
At least one of the -c or -s options must be specified. If one of
them is not specified, it is assumed to be the local host.
authmethod is a specifically ordered list of keywords that is only needed
if authenticated communication is wanted with recvhost. These keywords
are used to describe the type of communication and authentication that should
be used to contact the recvhost. If recvhost and sendhost
share the same authentication methods and identities, it is possible to
specify the authmethod for both recvhost and sendhost using the
-A argument. An authmethod specified with the -c option
will override an authmethod specified with the -A argument for
communication with the recvhost.
The format for authmethod and a description of the currently available
authentication methods are described with the -A argument.
- -k
-
- -s sendhost[:port] [authmethod]
- Specifies the host that will run the Iperf, Thrulay or Nuttcp client. The :port suffix is optional and is only needed if bwctld is being run on a non-default port number. If an IPv6 address is being specified, note that the accepted format contains the sendhost portion of the specification in square brackets as: [fe80::fe9f:62d8]:4823. This ensures the port number is distinct from the address specification, and is not needed if the :port suffix is not being used.
At least one of the -c or -s options must be specified. If one of
them is not specified, it is assumed to be the local.
authmethod is a specifically ordered list of keywords that is only needed
if authenticated communication is wanted with sendhost. These keywords
are used to describe the type of communication and authentication that should
be used to contact the sendhost. If recvhost and sendhost
share the same authentication methods and identities, it is possible to
specify the authmethod for both recvhost and sendhost using the
-A argument. An authmethod specified with the -s option
will override an authmethod specified with the -A argument for
communication with the sendhost.
The format for authmethod and a description of the currently available
authentication methods are described with the -A argument.
- -U
-
Throughput Test Arguments:¶
The arguments were named to match their counterparts in Iperf as closely as possible. Some of the options are not available for some of the throughput testers. BWCTL does not support UDP tests, changing the output format or changing the output units for either Nuttcp or Thrulay.- -T
- Specify which throughput tester to use:
- iperf
- thrulay
- nuttcp
- Default:
- None. Selects a tool that the client and server have in common
- -S TOS
-
- Default:
- None.
- -D DSCP
-
Name | Value | Service Class | Examples |
NONE | 000000 | Standard | Undifferentiated |
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.
- -b bandwidth
- Limit UDP send rate to bandwidth (bits/sec).
- Default:
- 1 Mb
- -i interval
- Report interval (seconds).
- Default:
- unset (no intervals reported)
- -l len
- length of read/write buffers (bytes).
- Default:
- 8 KB TCP, 1470 bytes UDP
- -P nStreams
- Number of concurrent streams for the test. See the -P option of Iperf for details.
- -S TOS
- Set the TOS (See RFC 1349) byte in packets.
- Default:
- 0 (not set)
- -t time
- Duration of test (seconds).
- Default:
- 10
- -u
-
- Default:
- TCP test
- -W window
- Same as the -w option, except that the value is advisory. bwctl will attempt to dynamically determine the appropriate TCP window, based upon RTT information gathered from the control socket. If bwctl is unable to dynamically determine a window, the value window will be used.
- Default:
- Unset (system defaults)
- -w window
- Socket buffer sizes (bytes). For TCP, this sets the TCP window size. For UDP, this sets the socket receive buffer size.
- Default:
- Unset (system defaults)
Scheduling Arguments:¶
- -a syncfuzz
-
If two systems do NOT have a close enough notion of time, then the throughput
test will eventually fail because one endpoint of the test will attempt to run
at a different time than the other.
If the operating system supports the NTP system calls, and the system
clock is determined to be unsynchronized, error messages will still be
reported depending upon the value of the -e flag.
When calculating the time errors, this value will be aded in to account for the
difference. The maximum time offset can be bounded on the server side, using
the max_time_error directive, to prevent a denial of service attack. If set,
the server will reject any requests to test with a peer that has too high a
timestamp error.
- Default:
- Unset (Defaults to Set for systems without the NTP system calls)
- -I interval
- Specifies that bwctl should attempt to run a throughput test every interval seconds.
- Default:
- Unset. If it is unset, bwctl only runs the test once.
- -L longest
- Specifies the longest amount of time the client is willing to wait for a reservation window. When bwctl requests a test from the bwctld server, it specifies the earliest time and the latest time it is willing to accept. The latest time is determined by adding this longest option to the earliest time. The earliest time is essentially 'now'. The longest time is specified as a number of seconds.
- Default:
- If interval is set, the default is 50% of interval. Otherwise, the default is twice the test duration time but no smaller than 5 minutes. (See -t.)
- -n nIntervals
- Number of tests to perform if the -I option is set.
- Default:
- Continuous
- -R alpha
- Randomize the start time of the test within this alpha percent of the interval. Valid values for alpha are from 0-50. bwctl will attempt to run the test every interval +/- alpha percent. For example, if the interval is 300 seconds and alpha is set to 10 percent, then bwctl will attempt to run a test every 270-330 seconds. This option is only useful with the -I option.
- Default:
- 0 (no randomness)
Output Arguments:¶
- -d dir
- Specifies directory for results files if the -p option is set.
- -e facility
- Syslog facility to log messages to.
- Default:
- LOG_USER
- -f units
- Specify the units for the tool to use when displaying the results. The accepted values for units are tool specific.
- Iperf:
- k
- Kilobits per second
- K
- Kilobytes per second
- m
- Megabits per second
- M
- Megabytes per second
- -h
-
- -p
-
- -q
-
- -r
-
- -V
-
- -v
-
- -x
-
- -y format
- Specify the output format of the tool. The accepted values for format are tool specific.
- Iperf:
- c
- [c]omma-separated output
ENVIRONMENT VARIABLES¶
bwctl Environment Variable | use | default |
BWCTLRC | Config file | ~/.bwctlrc |
BWCTL_DEBUG_TIMEOFFSET | Offset | 0.0(seconds) |
LIMITATIONS¶
Only tested with versions 1.7.0 and 2.0.b of Iperf.EXAMPLES¶
bwctl -c somehost.example.com- Run a default 10 second TCP test as soon as possible with local as the sender and somehost.example.com as the receiver, using whichever tools they have in common. Return the results from the receive side of the test.
- Like the previous test, but also return the results from the sender side of the test.
- Like the previous test, but with otherhost.example.com as the sender instead of local.
- Run a 30 second TCP Iperf test with somehost.example.com as the sender and local as the receiver.
- Run a 10 second UDP test about every hour (3600 +/- 360 seconds) with the sender rate limited to 10 Mbits per second from somehost.example.com to local.
- Run the default 10 second TCP test. Authenticate using the identity someuser. bwctl will prompt for a passphrase that will be used to create an AES key.
SEE ALSO¶
bwctld(8) and the http://e2epi.internet2.edu/bwctl/ web site. For details on Iperf, see the http://sourceforge.net/projects/iperf web site. For details on Nuttcp, see the http://www.wcisd.hpc.mil/nuttcp/Nuttcp-HOWTO.html web site. For details on Thrulay, see the http://e2epi.internet2.edu/thrulay/ 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: 2012-03-26 23:09:35 -0400 (Mon, 26 Mar 2012) $ |