Provided by: bwctl-client_1.4.1~rc2-1_amd64 
NAME
bwctl - Client application to request throughput tests.
SYNOPSIS
bwctl [options] -c recvhost -s sendhost
bwctl [options] -c recvhost
bwctl [options] -s sendhost
DESCRIPTION
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.
bwctl works by contacting a bwctld daemon on both the receiving host and the sending host.
bwctld manages and schedules the resources of the host it runs on. In the case where only
one of the receiving host or sending host is specified, bwctl assumes the local host is
the other endpoint. bwctl will attempt to contact a local bwctld if it can. If there is no
local bwctld running, bwctl assumes the local host does not require policy controls and
will execute the bwctld functionality required to run the test directly.
If cases where bwctl is directly running the throughput test on the host, there are
several configuration options that are shared with bwctld. Those configuration options can
be set using the bwctlrc(5) configuration file in a way very similar to the way they are
specified in the bwctld.conf(5) file.
The bwctl client is used to request the desired type of throughput test. Furthermore, it
requests when the test is wanted. bwctld on each endpoint either responds with a
tentative reservation or a test denied message. Once bwctl is able to get a matching
reservation from both bwctld processes (one for each host involved in the test), it
confirms the reservation. Then, the bwctld processes run the test and return the results.
The results are returned to the client from both sides of the test from the respective
bwctld processes. Additionally, the bwctld processes share the results from their
respective side of the test with each other.
BWCTL (bwctl and bwctld) is used to enable non-specific throughput tests to hosts without
having to give full user accounts on the given systems. Users want the ability to run
throughput tests to determine the achievable or available bandwidth between a pair of
hosts. It is often useful to test to multiple points along a network path to determine the
network characteristics along that path. Typically, users who want to do this path
decomposition have to directly contact the network/system administrators who control the
hosts along the path. The administrator needs to either run half of the test for the user
or give them a user account on the host. Also, network paths of interest are typically
controlled by multiple administrators. These hurdles have made this kind of testing
difficult in practice.
BWCTL was designed to help with this problem. It allows an administrator to configure a
given host as an Iperf, Thrulay, or Nuttcp endpoint. The endpoint can be a packet sender
(e.g. Iperf client) or a packet receiver (e.g. Iperf server). It can be shared by multiple
users without concern that those users will interfere with each other. Specific policy
limits can be applied to specific users, and individual tests are scheduled so they will
not interfere with each other. Additionally, full user accounts are not required for the
users running the tests.
BWCTL allows the administrator to classify incoming connections based upon a user name and
AES key combination or, alternatively, based upon an IP/netmask. Once the connection is
classified, the bwctld can determine the exact type and intensities of througput tests
that will be allowed. More information on the policy controls can be found in the
bwctld(8) man page.
BWCTL makes use of a distributed scheduling algorithm. Each host maintains a schedule
independently. As a client requests a test, the two endpoints are contacted and each
bwctld server responds with the first available open schedule slot. This enables on-demand
tests to co-exist with regularly scheduled tests since regularly scheduled tests are
implemented by having the client request tests on regular intervals. Different priorities
can be implemented using the event_horizon configuration directive to bwctld. (By allowing
clients that implement regularly scheduled tests to reserve their time slots further into
the future.)
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]
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.
The client can specify all the modes with which it is willing to
communicate. The most strict mode that both the server and the client are
willing to use will be selected.
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
authscheme and schemeopts are only needed if authenticated communication (A or E
modes of authmode) is wanted with sendhost and recvhost.
-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
This option has been deprecated. Originally, it was used to specify the keyfile for
authentication. All authentication options can now be specified using the -A
argument. For the next several versions this option will report an error.
Eventually, it may be reclaimed for another purpose.
-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
This option has been deprecated. Originally, it was used to specify the username to
identify the AES key for authentication. All authentication options can now be
specified using the -A argument. For the next several versions this option will
report an error. Eventually, it may be reclaimed for another purpose.
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
Set the TOS byte in the sending packets.
Default:
None.
-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.
-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
UDP test.
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
Allow bwctl to run without a synchronized system clock. Use this to specify how far
off the local clock is from UTC. bwctl prefers to have an NTP synchronized system
clock to ensure the two endpoints of the test are actually agreeing to the same
scheduled time window for test execution.
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
Print a help message.
-p
Place test results in files. Print the filenames to stdout when results are
complete.
-q
Quiet output. Output as little as possible.
-r
Send syslog messages to stderr. This is the default unless the -q option is
specified so this option is only useful with the -q option.
-V
Print version information and exit.
-v
Verbose output. Specifying additional -v's increases the verbosity.
-x
Output sender (client) results as well as receiver results. By default, sender
results are not output. If the -p option is specified, the sender results are
placed in an additional file.
-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.
bwctl -x -c somehost.example.com
Like the previous test, but also return the results from the sender side of the
test.
bwctl -x -c somehost.example.com -s otherhost.example.com
Like the previous test, but with otherhost.example.com as the sender instead of
local.
bwctl -t 30 -T iperf -s somehost.example.com
Run a 30 second TCP Iperf test with somehost.example.com as the sender and local as
the receiver.
bwctl -I 3600 -R 10 -t 10 -u -b 10m -s somehost.example.com
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.
bwctl -s somehost.example.com AE AESKEY someuser
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) $ bwctl(1)