|
Bandwidth Test Controller (BWCTL)
|
|
bwctl(1) Manual Page
bwctl(1) bwctl(1)
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
Iperf throughput tests.
From the Iperf web site:
Iperf is a tool to measure maximum TCP bandwidth, allowing the
tuning of various parameters and UDP characteristics. Iperf
reports bandwidth, delay jitter, datagram loss.
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.
The bwctl client is used to request the type of Iperf test wanted. Fur-
thermore, it requests when the test is wanted. bwctld on each endpoint
host either responds with a tentative reservation or a test denied mes-
sage. 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 Iperf tests to
hosts without having to give full user accounts on the given systems.
Users want the ability to run Iperf 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 char-
acteristics along that path. Typically, users that want to do this path
decomposition have to directly contact the network/system administra-
tors that 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 administra-
tor to configure a given host as an Iperf endpoint. The endpoint can
be a packet sender (Iperf client) or a packet receiver (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 Iperf tests that will be
allowed. More information on the policy controls can be found in the
bwctld(8) man page.
ARGUMENTS
Connection/Authentication Arguments:
-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 client. 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 con-
nection. 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 auth-
scheme 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. key-
file can be generated using the aespasswd(1)
application.
Default:
Unauthenticated.
authscheme and schemeopts are only needed if authenticated com-
munication (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 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 speci-
fied, note that the accepted format contains the recvhost por-
tion of the specification in square brackets as:
[fe80::fe9f:62d8]:4823. This ensures the port number is dis-
tinct 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 localhost.
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 com-
munication and authentication that should be used to contact the
recvhost. If recvhost and sendhost share the same authentica-
tion methods and identities, it is possible to specify the auth-
method for both recvhost and sendhost using the -A argument. An
authmethod specified with the -c option will override an auth-
method 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 argu-
ment.
-k
This option has been deprecated. It was used to specify the key-
file 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 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 speci-
fied, note that the accepted format contains the sendhost por-
tion of the specification in square brackets as:
[fe80::fe9f:62d8]:4823. This ensures the port number is dis-
tinct 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 localhost.
authmethod is a specifically ordered list of keywords that is
only needed if authenticated communication is wanted with send-
host. These keywords are used to describe the type of communi-
cation and authentication that should be used to contact the
sendhost. If recvhost and sendhost share the same authentica-
tion methods and identities, it is possible to specify the auth-
method for both recvhost and sendhost using the -A argument. An
authmethod specified with the -s option will override an auth-
method 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 argu-
ment.
-U
This option has been deprecated. It was used to specify the
username to identify the AES key for authentication. All
authentication options can now be specified using the -A argu-
ment. For the next several versions this option will report an
error. Eventually it may be reclaimed for another purpose.
Throughput Test Arguments:
(These arguments were named to match their counterparts in Iperf as
closely as possible.)
-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 nThreads
Generates an error message. The -P option of Iperf is not cur-
rently supported by bwctl.
-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 win-
dow, 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
Allow bwctl to run without a synchronized system clock. 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. This option is used
to bypass this requirement for systems that either do not have
the NTP system calls, or prefer not to configure NTP.
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.
Default:
Unset (Defaults to Set for systems without the NTP system
calls.)
-I interval
Specifies that bwctl should attempt to run the Iperf test every
interval seconds.
Default:
Unset. If it is unset, bwctl only runs the test once.
-L latest
Specifies the latest 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 option is specified as a number of
seconds that will be added to the start time.
Default:
If interval is set, the default is 50% of interval. Oth-
erwise, 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.
-h
Print a help message.
-p
Place Iperf 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 ver-
bosity.
-x
Output sender (Iperf 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 addi-
tional file.
ENVIRONMENT VARIABLES
If bwctl is directly running the Iperf test on the host then it will be
executing some of the bwctld functionality directly. In some cases it
might be useful to specify some of the configuration options that can
be specified for bwctld in this context. The following Environment
Variables can be used to specify those configuration options:
bwctl Environment Variable bwctld.conf Option
------------------------------------------------
BWCTL_IPERFPORTRANGE iperfport
BWCTL_IPERFCMD iperfcmd
BWCTL_BOTTLENECKCAPACITY bottleneckcapacity
BWCTL_SYNCFUZZ syncfuzz
BWCTL_CONTROLTIMEOUT controltimeout
BWCTL_PEERPORTS peerports
See the bwctld.conf(5) man page for details on these options.
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 Iperf test as soon as possible with
localhost as the sender and somehost.example.com as the
receiver. 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 localhost.
bwctl -t 30 -s somehost.example.com
Run a 30 second TCP Iperf test with somehost.example.com as the
sender and localhost 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 some-
host.example.com to localhost.
bwctl -s somehost.example.com AE AESKEY someuser
Run the default 10 second TCP Iperf 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/ and
http://dast.nlanr.net/Projects/Iperf/ web sites.
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: 2005/09/07 23:36:18 $ bwctl(1)
Man(1) output converted with
man2html
|
|
| Bandwidth Test Controller (BWCTL) |
16 February, 2004 |
|
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.
|
|
