Connection/AuthenticationArguments:-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).
-Aauthmethodauthmethod 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[authschemeschemeopts]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"
authschemeschemeoptsauthscheme 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):
AESKEYuserid[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_addresssrcaddr
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,--receiverrecvhost[: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,--sendersendhost[: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.
bwctlTestArguments:
The arguments were named to match their counterparts in Iperf as closely as possible.
-T,--tool
Specify which throughput tester to use:
iperfiperf3nuttcp
Default:
None. Selects a tool that the client and server have in common
-S,--tosTOS
Set the TOS byte in the sending packets.
Default:
None.
-D,--dscpDSCP
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 │ ServiceClass │ 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,--bandwidthbandwidth
Limit UDP send rate to bandwidth (bits/sec).
Default:
1 Mb
-i,--report_intervalinterval
Report interval (seconds).
Default:
unset (no intervals reported)
-l,--buffer_lengthlen
length of read/write buffers (bytes).
Default:
8 KB TCP, 1470 bytes UDP
-O,--omitseconds
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,--parallelnStreams
Number of concurrent streams for the test. See the -P option of Iperf for details.
-t,--test_durationtime
Duration of test (seconds).
Default:
10
-u,--udp
UDP test.
Default:
TCP test
-W,--dynamic_windowwindow
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,--windowwindow
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)
bwpingTestArguments:-T,--tool
Specify which throughput tester to use:
pingowamp
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_lengthlength
The size of the packets to send for the ping or owamp test
Default:
Minimally sized packets
-N,--num_packetsnPackets
The number of packets to send in this test
Default:
10
-i,--packet_intervalseconds
The time between when each packet is sent for the test
Default:
1.0 seconds
-t,--ttlttl
The TTL value to tag each packet with. This only applies to ping tests.
Default:
None
bwtracerouteTestArguments:-T,--tool
Specify which throughput tester to use:
traceroutetracepath
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_lengthlength
The size of the packets to send for the tests
Default:
Minimally sized packets
-F,--first_ttlttl
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_ttlttl
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_durationsecondsfR
The maximum amount of time to wait for the traceroute test to finish.
Default:
10 seconds
SchedulingArguments:-a,--allow_ntp_unsyncsyncfuzz
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_intervalinterval
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_timelongest
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_testsnIntervals
Number of tests to perform if the -I option is set.
Default:
Continuous
-R,--randomizealpha
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)
OutputArguments:-d,--output_dirdir
Specifies directory for results files if the -p option is set.
-e,--facilityfacility
Syslog facility to log messages to.
Default:
LOG_USER
-f,--unitsunits
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,--formatformat
Specify the output format of the tool. The accepted values for format are tool specific.
Iperf:
c [c]omma-separated output
Install Now
PNG Icons
SVG Icons