* What is Bredbandskollen?

Bredbandskollen is a consumer tool that helps broadband customers evaluate their
broadband Internet connection. By using Bredbandskollen the consumer gets a test
result which is then evaluated. Feedback is given on how well this result is
consistent with the expected capacity of the Internet connection as promised by
the service provider.

Bredbandskollen is a registered trademark of IIS
(The Internet Foundation in Sweden).


* Bredbandskollen's command line tool

To perform a measurement, execute the command

    bbk_cli

Example:

    $ bbk_cli
    Network operator: Com Hem AB
    Support ID: sth26a3f1e2d
    Latency:       6,990 ms
    Download:    250,125 Mbit/s
    Upload:        9,774 Mbit/s
    Service provider: Comhem
    Subscription: 150-250 Mbit/s kabeltv
    The download result is GOOD
    Measurement ID: 257713310
    $

The latency result is the average response time in milliseconds.
The download result is the average speed during 10 seconds of download.
The upload result is the average speed during 10 seconds of upload.
If the bbk_cli command doesn't work as expected, and you want to contact
Bredbandskollen's support team, please include the support ID (aka "ticket") or
measurement ID given in the output.

If the subscription can be identified, the download result will be evaluated as
"GOOD", "ACCEPTABLE", or "BAD". The result is considered BAD if the speed is
below the lower end of the expected speed range as stated by the service
provider. It is considered ACCEPTABLE if it is above the lower end, but still
clearly below the middle, of the expected speed range. If the result is better,
it is considered GOOD.
E.g. if the expected range is 150-250 Mbit/s, a result below 150 is BAD; a
result between 150 and 190 is ACCEPTABLE, and a result above 190 is GOOD.

Before the first measurement is performed, information about data collection is
given. During the measurement, and when evaluating the result, the server has to
process the user's ip number and some related information. No measurement can be
performed unless the user agrees to that.

Note: DO NOT run the application as a privileged user; that would greatly
increase the security risk.

* Command line options

--help

  Show help text.


--v6

  Measure over IPv6. This will only work if you have an IPv6 address.


--local-ip=IP

  If the computer has more than one connection to the internet, perform the
  measurement using the network interface with local ip number IP.
  This will only work on platforms using the "strong host" model.
  E.g. most Linux systems use the "weak host" model, so this option will simply
  not work on Linux.


--proxy-host=HOST

  Use HTTP proxy server HOST.
  Note: The measurement is performed using a protocol similar to HTTP/1.1.
  It should work through most (albeit not all) HTTP proxy servers.
  In particular, some parts of the measurement may use the web socket
  protocol, which may be blocked by some proxy servers.


--proxy-port=PORT

  Use port PORT on proxy server (default 80)


--server=HOST

  Use HOST as measurement server. E.g. HOST could be the server's
  domain name (sth6.bredbandskollen.se) or ip number (192.36.30.2).
  For a list of servers, see the --check-servers option below.


--port=N

  Port number for measurement server, default 80.


--duration=N

  Measure upload/download for N seconds (2-10, default 10).
  In general, stable connections require shorter duration.


--speedlimit=N

  Keep upload/download speed below N mbps on average.


--test

  Perform a test measurement. It normally works like a standard measurement, but
  the measurement is performed at Bredbandskollen's betatest server. The result
  will not be used in Bredbandskollen's statistical reports.


--live

  Perform standard measurement, the opposite of --test.
  This is the default.


--local

  Don't fetch configuration from Bredbandskollen's server, i.e. neither --live
  nor --test. For this to work, you must provide the ip address to a measurement
  server using the --server option. The server could be one of Bredbandskollen's
  measurement servers (you can find a list of servers using the --check-servers
  option), or a server owned by you or by a third party.
  This is useful if you want to perform a measurement on a local network or if
  there is no working domain name server (then give the ip number instead of the
  domain name as the value of the --server parameter).


--run-server

  Don't perform a measurement; run as a measurement server instead. This might
  be useful for testing modified measurement clients, or if you want to
  perform a measurement on a local network instead of over the internet.
  On the server host, you should run e.g.

     bbk_cli --run-server --listen=8080

  and on the client host, you then run e.g.

     bbk_cli --local --server=192.168.0.20 --port=8080

  where 192.168.0.20 should be replaced by the server's ip address. The server
  log will by default be written to  $HOME/.bredbandskollen/server_log .
  Note: this is not a fully-featured or optimised measurement server.


--log=FILENAME

  Write a debug log to FILENAME. Default is $HOME/.bredbandskollen/last_log .
  Use --log=- to get the debug output on the console (standard error).


--check-servers

  A quick check is performed against a list of measurement servers. The response
  time for each server is shown. A single package is sent and returned by each
  server, so the results may vary a lot between different runs. Still, the
  result will give a rough estimate of the "best" measurement server.
  Note: A more distant server might still have better throughput for download
  or upload measurement. If you have a very fast connection (above 5 Gbit/s),
  only a few servers will have enough bandwidth to give a good download result.


--measurements

  List 10 last measurements performed from the current device.
  If --quiet option is given, output will be JSON.
  Otherwise output will be lines with tab separated fields.


--measurements=N

  List N last measurements instead of the last 10.


--from-id=N

  List only measurements before Measurement ID N.


--browser

  Use a web browser (instead of the terminal) as interface during the
  measurement.

  Note: the measurement will still be performed by the bbk_cli application; the
  web browser will only be used as a GUI showing the result.

  The client will try to open a tab in the system's default browser. You will
  have to press a button in the web browser tab to start the measurement. When
  the tab is closed, the bbk_cli application will exit.

  Note: the source code for the web page shown in the browser tab is fetched
  from Bredbandskollen's server, but the communication between the bbk_cli
  application and the browser is local, through a websocket connection between
  the browser and a port opened by the bbk_cli application.

  Sometimes, bbk_cli will fail to automatically open a browser window. If so,
  you could give the option --listen=0 instead; see below.


--listen=PORT

  Use web browser as interface. The browser must connect to the given PORT using
  an URL that will be written to the terminal window.
  The user must manually start a web browser on the same computer and then paste
  the URL into the web browser.
  If PORT is 0, a random port number will be allocated. A port number below 1024
  will not work since the application should be run by an unprivileged user.
  Note: bbk_cli will act as a server, waiting for the browser to connect. Only a
  single connection will be accepted. When the browser tab is closed, bbk_cli
  will terminate.
  A one-time password will be generated and used to protect against unauthorised
  users connecting to bbk_cli before the intended user.


--listen-addr=IP

  Note: DO NOT use this option unless you know exactly what you are doing.
  This option may only be used together with the above --listen option.
  This option is necessary if you want to run the measurement on a certain
  device, but want to use a browser on another computer as an interface.

  The bbk_cli application will open a server socket, listening on ip address IP
  and the port given by the --listen option.
  Note: this may not work due to e.g. firewalls. Actually, this option should
  only be used on local networks that are protected from the public internet by
  a firewall.


--listen-pw=PW

  Use PW as one-time password when connecting from browser (by default, a random
  password will be generated.)
  Use this if you need to have a predictable URL for the browser to connect to.
  Note: DO NOT EVER reuse a sensitive password for this option. The password may
  be sent unencrypted over the network, and might also be written to temporary
  logs.


--quiet

  Write a single line of output.
  Four or five strings will be written, separated by a white space character.
  The first string is the latency result in milliseconds. The second and third
  are the download and upload results in Mbps. The fourth is the support ID.
  If the download result could be evaluated, the evaluation will be the fifth
  and last output string: GOOD, ACCEPTABLE or BAD.
  NOTE! If a particular subtest fails, the result will be a value <= 0.


--out=FILENAME

  Append output to FILENAME instead of writing to the console.


* How does Bredbandskollen's CLI tool work?

1. Configuration data is retrieved from Bredbandskollen's API servers. The most
   important part of the data is a list of active measurement servers. The data
   may also include the name of the network operator or internet service,
   provider. The operator is detected from the user's ip number using public
   information. In rare cases, the detection will fail due to e.g. recent changes
   that haven't yet been updated in the information databases.
   The configuration data may also include a cookie, i.e. a completely random
   identification string. Bredbandskollen uses the cookie only to determine
   whether different measurements are performed by the same device or not.
   This cookie will be called the device's "key" or "hashkey". It will be stored
   in a local file: $HOME/.bredbandskollen/config .

   The --live, --test, and --local options determine from which server the
   configuration is retrieved.


2. The measurement server closest to your connection's external IP number will
   be chosen by default. This will not always be the "best" server. Also,
   sometimes our estimate of the IP number's geographical position will be
   completely wrong; in particular, if the ip number belongs to a mobile
   connection, the position will often be wrong.
   The default choice can be overridden using the --server option.

3. The measurement client fetches a "ticket", a 12 character string, from the
   measurement server. The ticket is used as an identification of all
   connections belonging to the same measurement.  Note: the ticket is a
   temporary cookie for a single measurement, whereas the hash key is a more
   permanent cookie for the device the client application runs on.

4. A latency measurement is performed. Small packets of data are sent back and
   forth between the client and the measurement server. The average roundtrip
   time, after removing up to 40% of the worst samples, will be used as the
   result.

5. The client's estimate of the latency information and some information about
   the client application, is sent to the measurement server in order to
   configure the measurement and to ask the measurement server to try to
   identify the user's subscription type.
   E.g. the client application's name and version number, what platform it runs
   on, the ticket and/or a cookie (a "binary" version of the ticket), and the
   user's ip number is sent.
   The Measurement server will try identify the subscription type, if possible
   in cooperation with the service provider that owns the ip number the
   measurement is performed through. E.g. the service provider could be Telia,
   Bahnhof, Com Hem, Bredbandsbolaget, Telenor or Tre.
   The measurement server will respond immediately with a limited amount of
   information, in particular, the user's external (internet accessible)
   ip number, which may be different from the device's local ip number due to
   e.g. network address translation. Detection of subscription type may take a
   few seconds, if at all possible. The actual result will arrive asynchronously
   and will be used at the end of the measurement to evaluate the result.

6. Download measurement starts. At the start of the download measurement, 10
   simultaneous connections to the measurement server will be used. If the
   connection is fast, more connections (up to 48 in total) will be added.
   Through each connection, data is sent using the HTTP/1.1 protocol. At
   first, small "files" are sent. If the connection is fast, file sizes will
   increase. The file sizes will decrease near the end of the download
   measurement. The data sent by the server is completely random, so it would
   be rather pointless to encrypt it using SSL.
   Note: using a lot of simultaneous connections may be "brutal", but it is
   the only way to get good results, in particular it the connection is very
   fast or unreliable (with a lot of retransmissions or dropped packages), or
   if there is other traffic on the same connection.

7. Upload measurement starts. Completely random data is sent using 4
   simultaneous connections. The client will keep track of the amount of data
   sent from the application in order to estimate the upload speed, but
   the local speed estimate may be wildly inaccurate since the data sent may
   still reside in local buffers or in proxy servers. To get reliable results,
   the server will regularly report the current upload speed to the client.
   Sometimes there may be a "lag" in the speed reported by the server, but
   the result will still be corrent in the end.

8. The client sends its estimate of the measurement result to the server.
   The server responds with all available information: the official latency,
   upload and download results, the subscription type (if it could be
   identified), and some miscellaneous information like the number of bytes
   transferred, number of connections, number of dropped packages etc.
   A message from the service provider (generated at the start of the
   measurement) may also be included.

9. The measurement server assigns a unique ID number for the measurement, and
   also checks the network operator for updated info. The result is sent back
   to the measurement client.