Provided by: bwctl-client_1.5.4+dfsg1-1build1_amd64 
NAME
bwctl, bwping, bwtraceroute - Client application to request throughput, traceroute, ping and owamp tests.
SYNOPSIS
bwctl [options] -c recvhost -s sendhost
bwctl [options] -c recvhost
bwctl [options] -s sendhost
bwping [options] -c recvhost -s sendhost
bwping [options] -c recvhost
bwping [options] -s sendhost
bwtraceroute [options] -c recvhost -s sendhost
bwtraceroute [options] -c recvhost
bwtraceroute [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, Iperf3, Ping, Traceroute, Tracepath and
Owamp 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 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, bwping and bwtraceroute clients are used to request the desired type of throughput, latency or
traceroute 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 network measurement 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, Iperf3, Nuttcp, or Owamp 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, --ipv4
Forces bwctl to use IPv4 addresses only.
Default:
Unspecified (IPv6 is preferred).
-6, --ipv6
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, --local_address 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, --receiver recvhost[:port] [authmethod]
Specifies the host that will run the Iperf, Iperf3 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.
-s, --sender sendhost[:port] [authmethod]
Specifies the host that will run the Iperf, Iperf3 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.
-o, --flip
By default, the sender will connect to the receiver. The --flip option causes the receiver to
connect to the sender. This option is not available for all test types (e.g. for iperf tests).
This is most useful if the receiver is behind a firewall.
bwctl Test Arguments:
The arguments were named to match their counterparts in Iperf as closely as possible.
-T, --tool
Specify which throughput tester to use:
iperf
iperf3
nuttcp
Default:
None. Selects a tool that the client and server have in common
-S, --tos TOS
Set the TOS byte in the sending packets.
Default:
None.
-D, --dscp 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 bandwidth
Limit UDP send rate to bandwidth (bits/sec).
Default:
1 Mb
-i, --report_interval interval
Report interval (seconds).
Default:
unset (no intervals reported)
-l, --buffer_length len
length of read/write buffers (bytes).
Default:
8 KB TCP, 1470 bytes UDP
-O, --omit seconds
Initial period of data to omit from the final statistics. This is so that you can skip past
initial conditions such as TCP Slow Start. Currently only implemented by the iperf3 tool.
-P, --parallel nStreams
Number of concurrent streams for the test. See the -P option of Iperf for details.
-t,--test_duration time
Duration of test (seconds).
Default:
10
-u, --udp
UDP test.
Default:
TCP test
-W,--dynamic_window 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 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)
bwping Test Arguments:
-T, --tool
Specify which throughput tester to use:
ping
owamp
Default:
None. Selects a tool that the client and server have in common
-E, --no_endpoint
Allow a ping test to run where the receiver may not have bwctl available.
-l, --packet_length length
The size of the packets to send for the ping or owamp test
Default:
Minimally sized packets
-N, --num_packets nPackets
The number of packets to send in this test
Default:
10
-i, --packet_interval seconds
The time between when each packet is sent for the test
Default:
1.0 seconds
-t, --ttl ttl
The TTL value to tag each packet with. This only applies to ping tests.
Default:
None
bwtraceroute Test Arguments:
-T, --tool
Specify which throughput tester to use:
traceroute
tracepath
Default:
None. Selects a tool that the client and server have in common
-E, --no_endpoint
Allow a test to run where the receiver may not have bwctl available.
-l, --packet_length length
The size of the packets to send for the tests
Default:
Minimally sized packets
-F, --first_ttl ttl
The minimum TTL to set for traceroute. This sets the first hop in the route that will be returned.
This does not work for tracepath tests.
Default:
None
-M, --max_ttl ttl
The maximum TTL to set for traceroute. This sets the last hop in the route that will be returned.
This does not work for tracepath tests.
Default:
None
-t, --test_duration secondsfR
The maximum amount of time to wait for the traceroute test to finish.
Default:
10 seconds
Scheduling Arguments:
-a, --allow_ntp_unsync 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, --test_interval 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, --latest_time 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 10 minutes. (See -t.)
-n, --num_tests nIntervals
Number of tests to perform if the -I option is set.
Default:
Continuous
-R, --randomize 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, --output_dir dir
Specifies directory for results files if the -p option is set.
-e, --facility facility
Syslog facility to log messages to.
Default:
LOG_USER
-f, --units 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, --help
Print a help message.
-p, --print
Place test results in files. Print the filenames to stdout when results are complete.
-q, --quiet
Quiet output. Output as little as possible.
-r, --syslog_to_stderr
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, --version
Print version information and exit.
-v, --verbose
Verbose output. Specifying additional -v's increases the verbosity.
-x, --both
Output both sender and receiver results. By default, only the results from the appropriate side
for the given tool are output. If the -p option is specified, the sender results are placed in an
additional file.
-y, --format 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)
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.
bwping --no_endpoint -N 30 -i 0.5 --ttl 150 -c somehost.example.com
Run a ping test that sends 30 pings, one packet per half-second, with a TTL of 150 to
somehost.example.com from local. If somehost.example.com does not have bwctl running, the ping
test runs anyway.
bwtraceroute -T tracepath -E -c somehost.example.com
Run a tracepath test to somehost.example.com from local. If somehost.example.com does not have
bwctl running, the tracepath test runs anyway.
SEE ALSO
bwctld(8) and the http://software/bwctl/ web site.
For details on Iperf3, see the https://github.com/esnet/iperf 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 Owamp, see the http://software.internet2.edu/owamp 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$ bwctl(1)