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.

SEE ALSO
---------

**sbws.ini** (5), https://tpo.pages.torproject.net/network-health/sbws,
https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt,
**tor** (1).

BUGS
----

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