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.

scanner setup

Install sbws according to INSTALL.rst (in the local directory or GitHub) 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 destination``s so that the ``scanner can continue if one fails.

If sbws is installed from the Debian package, then create a file in /etc/sbws/sbws.ini like in the following example:

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 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 GitHub) 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 GitHub) or man_sbws.html (local build or Read the Docs) or man sbws (system package).