Simple Bandwidth Scanner - SBWS(1)¶

SYNOPSIS¶

sbws [Optional arguments] [Positional arguments]

sbws [-h] [–version] [–log-level {debug,info,warning,error,critical}] [-c CONFIG] {cleanup,scanner,generate,init,stats}

DESCRIPTION¶

Tor bandwidth scanner that generates bandwidth measurements files to be read by the Directory Authorities.

The scanner requires a configuration file (see sbws.ini (5)) with a with a ‘[destinations]’ section.

sbws can be run a python script or a system service. The later is recommended.

The default locations of the files that sbws reads or generate depend on on how it is run. See the section FILES to know which are the default locations.

OPTIONS¶

Positional arguments¶

{cleanup,scanner,generate,init,stats}

These arguments can have additional optional arguments. To obtain information about them, run: ‘sbws <positional argument> –help’.

Optional arguments¶

-h, --help: Show help message and exit.
--version: Show sbws version and exit.

–log-level {debug,info,warning,error,critical}: Override the sbws log level (default: info).

-c CONFIG, --config CONFIG: Path to a custom configuration file.

EXAMPLES¶

sbws scanner: Run the scanner using sbws defaults.
sbws -c ~/.sbwsrc scanner: Run the scanner using the configuration file in ~/.sbwsrc
sbws –log-level debug generate: Generate v3bw file in the default v3bw directory.
sbws cleanup: Cleanup datadir and v3bw files older than XX in the default v3bw directory.

FILES¶

In the following list, the first path is the default location when running sbws as an script, the second path is the default location when running sbws as a system service.

$HOME/.sbws.ini or /etc/sbws/sbws.ini

Location where sbws searches for a custom configuration file, when the option –config is not provided.

$HOME/.sbws or /var/lib/sbws

Location where sbws writes/reads measurement data files, bandwidth list files and tor process data.

Under this directory, sbws creates the following subdirectories:

datadir
Raw results generated by the sbws scanner. Other commands (such as generate and stats) read results from this directory.

log
Log files generated by sbws, when logging to a file is configured (see sbws.ini).

v3bw
Bandwidth files generated by sbws generate. These are the files read by the Tor directory authorities.

tor
Data generated by the tor process launched by sbws.

$HOME/.sbws/tor or /run/sbws/tor

Location where the tor process launched by sbws scanner stores temporal files, like Unix domain sockets.

BUGS¶

Please report bugs at https://gitlab.torproject.org/tpo/network-health/sbws/-/issues/.