Deploying Simple Bandwidth Scanner

To run sbws is needed:

Both the scanner and your the destination (s) should be on fast, well connected machines.

destination requirements

  • A Web server installed and running that supports HTTP GET, HEAD and Range (RFC 7233) requests. Apache HTTP Server and Nginx support them.

  • TLS support to avoid HTTP content caches at the various exit nodes.

  • Certificates can be self-signed.

  • A large file; at the time of writing, at least 1 GiB in size It can be created running:

    head -c $((1024*1024*1024)) /dev/urandom > 1GiB

  • A fixed IP address or a domain name.

  • Bandwidth: at least 12.5MB/s (100 Mbit/s).

  • Network traffic: around 12-15GB/day.

If possible, use a Content delivery network (CDN) in order to make the destination IP closer to the scanner exit.

scanner setup

Install sbws according to INSTALL.rst (in the local directory or Tor Project Gitlab) or INSTALL.html (local build or Read the Docs).

To run the scanner it is mandatory to create a configuration file with at least one destination. It is recommended to set several destinations so that the scanner can continue if one fails.

If sbws is installed from the Debian package, then create the configuration file in /etc/sbws/sbws.ini. You can see an example with all the possible options here, note that you don’t need to include all of that and that everything that starts with # and ; is a comment:

Listing 1 Example sbws.example.ini
# Minimum configuration that needs to be customized
[scanner]
# A human-readable string with chars in a-zA-Z0-9 to identify your scanner
nickname = sbws_default
# ISO 3166-1 alpha-2 country code where the Web server destination is located.
# Default AA, to detect it was not edited.
country = SN

[destinations]
# With several destinations, the scanner can continue even if some of them
# fail, which can be caused by a network problem on their side.
# If all of them fail, the scanner will stop, which
# will happen if there is network problem on the scanner side.

# A destination can be disabled changing `on` by `off`
foo = on

[destinations.foo]
# the domain and path to the 1GB file.
url = https://example.com/does/not/exist.bin
# Whether to verify or not the TLS certificate. Default True
verify = False
# ISO 3166-1 alpha-2 country code where the Web server destination is located.
# Default AA, to detect it was not edited.
# Use ZZ if the location is unknown (for instance, a CDN).
country = ZZ

# Number of consecutive times that a destination could not be used to measure
# before stopping to try to use it for a while that by default is 3h.
max_num_failures = 3

## The following logging options are set by default.
## There is no need to change them unless other options are prefered.
; [logging]
; # Whether or not to log to a rotating file the directory paths.log_dname
; to_file = yes
; # Whether or not to log to stdout
; to_stdout = yes
; # Whether or not to log to syslog
; # NOTE that when sbws is launched by systemd, stdout goes to journal and
; # syslog.
; to_syslog = no

; # Level to log at. Debug, info, warning, error, critical.
; # `level` must be set to the lower of all the handler levels.
; level = debug
; to_file_level = debug
; to_stdout_level = info
; to_syslog_level = info
; # Format string to use when logging
; format = %(module)s[%(process)s]: <%(levelname)s> %(message)s
; # verbose formatter useful for debugging
; to_file_format = %(asctime)s %(levelname)s %(threadName)s %(filename)s:%(lineno)s - %(funcName)s - %(message)s
; # Not adding %(asctime)s to to stdout since it'll go to syslog when using
; # systemd, and it'll have already the date.
; to_stdout_format = ${format}
; to_syslog_format = ${format}

# To disable certificate validation, uncomment the following
# verify = False

If sbws is installed from the sources as a non-root user then create the configuration file in ~/.sbws.ini.

More details about the configuration file can be found in ./docs/source/man_sbws.ini.rst (in the local directory or Tor Project Gitlab) or man_sbws.ini.html (local build or Read the Docs) or man sbws.ini (system package).

See also ./docs/source/man_sbws.rst (in the local directory or Tor Project Gitlab) or man_sbws.html (local build or Read the Docs) or man sbws (system package).