---
name: "sbws"
section: "1"
platform: "linux"
package: "sbws"
version: "1.9.0-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sbws"
---

# sbws(1)

Simple Bandwidth Scanner

## NAME

sbws - Simple Bandwidth Scanner

## 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://spec.torproject.org/bandwidth-file-spec/*, **tor** (1).

## BUGS

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

## AUTHOR

Matt Traudt \[sirmatt at ksu dot edu\], juga \[juga at riseup dot net\]

## COPYRIGHT

CC0