SBWS(1)

📦
version 2.2.0 · 5 versions
, in ubuntu resolute, ubuntu stonking

✨ sbws 💖 the manual page bestie edition ✨

okay so you opened man sbws and now you're here, welcome, we're doing this together 🫶 this is the manual for sbws, and it's literally the whole thing, every flag, every path, no notes skipped. slay. let's go.

🌸 NAME 🌸

sbws — Simple Bandwidth Scanner. that's it, that's the name, it's giving exactly what it says on the tin 💅

🎀 SYNOPSIS 🎀

sbws [Optional arguments] [Positional arguments]

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

like. two ways to call her. either you're being vague and cute with [Optional arguments] and [Positional arguments], or you're being specific with the whole lineup of flags and the little menu of subcommands {cleanup,scanner,generate,init,stats} ✨

🦋 DESCRIPTION 🦋

so sbws is a Tor bandwidth scanner that generates bandwidth measurements files, and those files get read by the Directory Authorities. no cap. that's the whole job and she does it well 👑

here's the thing though: the scanner requires a configuration file (peep sbws.ini (5)) and that config needs a [destinations] section. no destinations section, no scanner, periodt.

you can run sbws as a python script or as a system service. the system service is the recommended one — that's the main character way to do it 💅

and listen, the default locations of all the files that sbws reads or generates? they depend on how it's run. so if you're like "where did my files go 😭" — go read the FILES section below, bestie, it's all laid out there.

💅 OPTIONS 💅

🌈 Positional arguments

  • {cleanup,scanner,generate,init,stats} — your subcommand menu, pick one bestie.

these arguments can have their own additional optional arguments. to find out what they are, literally just run:

sbws <positional argument> --help

and she'll tell you everything she knows 🫶

⭐ Optional arguments

  • -h, --help — shows the help message and dips. classic.
  • --version — shows the sbws version and dips.
  • --log-level {debug,info,warning,error,critical} — overrides the sbws log level. default is info. so if you want the tea, you pick debug 👀
  • -c CONFIG, --config CONFIG — path to a custom configuration file. bring your own config, icon behaviour.

🔥 EXAMPLES 🔥

okay the moment you've been waiting for, actual usage, let's get into it:

sbws scanner

run the scanner using sbws defaults. just vibes, no config file specified.

sbws -c ~/.sbwsrc scanner

run the scanner using the configuration file in ~/.sbwsrc 🌸

sbws --log-level debug generate

generate the v3bw file in the default v3bw directory, and yes, with debug logging so you can see everything 👀

sbws cleanup

cleanup datadir and v3bw files older than XX in the default v3bw directory. yes, XX. that's what the manpage says. it's mysterious. it's giving cryptic. we don't question her 🫶

💜 FILES 💜

okay important part, pay attention bestie. in this whole list, the first path is the default location when you run sbws as a script, and the second path is the default location when you run sbws as a system service. two lives, two paths, one legend ✨

  • $HOME/.sbws.ini or /etc/sbws/sbws.ini — the location where sbws goes looking for a custom configuration file, when the --config option isn't provided. (i.e. when you didn't tell her where to look, she looks here.)
  • $HOME/.sbws or /var/lib/sbws — the location where sbws writes/reads measurement data files, bandwidth list files and tor process data.

under this directory, sbws creates the following subdirectories:

  • datadir — the raw results generated by the sbws scanner. other commands (like generate and stats) read results from this directory. it's the source of truth, the origin story 🎀
  • log — the log files generated by sbws, when logging to a file is configured (peep sbws.ini).
  • v3bw — the bandwidth files generated by sbws generate. these are the files read by the Tor directory authorities. the whole point, lowkey 👑
  • tor — data generated by the tor process launched by sbws.
  • $HOME/.sbws/tor or /run/sbws/tor — the location where the tor process launched by the sbws scanner stores temporal files, like Unix domain sockets. temporary stuff, cute little sockets, love that for her 🦋

🧚 SEE ALSO 🧚

go read these too, iykyk:

💀 BUGS 💀

found a bug? don't suffer in silence bestie, 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]

legends, both of them, no further questions 💖

CC0

and that's the whole page bestie, you ate that 🫶 version 2.2.0, dated Oct 17, 2025, coming to you from the sbws manual. go run something and slay 💅✨

📦 where this page comes from