Internet2

Bandwidth Test Controller (BWCTL)

About    |    Downloads      |     Manual Pages     |     Cookbook (PDF)    |    License

bwctl(1)							      bwctl(1)



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 mea-
       surement 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.	 Typi-
       cally,  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 main-
       tains 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 config-
       uration directive to bwctld. (By allowing clients that implement	 regu-
       larly  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 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, --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  con-
	      tains the recvhost portion of the specification in square brack-
	      ets 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 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.

       -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 con-
	      tains the sendhost portion of the specification in square brack-
	      ets 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 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.

       -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  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 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 avail-
	      able.

       -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  tra-
	      cepath 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  tra-
	      cepath 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. Oth-
		     erwise, 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  ver-
	      bosity.

       -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	 some-
	      host.example.com to local.

       bwctl -s somehost.example.com AE AESKEY someuser

	      Run the default 10 second TCP test. Authenticate using the iden-
	      tity 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	 some-
	      host.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  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$			      bwctl(1)