Provided by: bwctl-client_1.5.4+dfsg1-1_amd64 bug

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.)

       ┌────────┬────────┬─────────────────────────┬───────────────────────────┐
       │ NameValueService ClassExamples          │
       ├────────├────────├─────────────────────────├───────────────────────────┤
       │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)