# Deploying Simple Bandwidth Scanner

To run sbws is needed:

- A machine to run the scanner.

- One or more destination (s) that serve a large file.

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 preferred.
    ; [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).