SBWS.INI(5)

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

💖 SBWS.INI 💖

okay so bestie, welcome to sbws.ini(5) — the manual page for the Simple Bandwidth Scanner configuration file. it's giving "one text file runs the whole scanner" energy and honestly? iconic. let's get into it 🫶

✨ NAME ✨

sbws.ini — Simple Bandwidth Scanner configuration 🌸

🎀 DESCRIPTION 🎀

so this is the Tor bandwidth scanner configuration file. that's the whole vibe. 💅

the sbws (1) scanner command needs a configuration file that has these sections:

  • [scanner]
  • [destinations]
  • [destinations.<name>]

and there has to be at least one [destinations.<name>]. no cap, that one's required, not optional. 🙈

if you want to see a minimal configuration that actually works, peep the EXAMPLES further down. ⬇️

🌈 SECTIONS 🌈

🌟 general 🌟

  • data_period = INT — how many days back in the past measurements are still considered valid. (Default: 5)
  • http_timeout = INT — timeout in seconds handed to the python Requests library. (Default: 10)
  • circuit_timeout = INT — timeout in seconds for creating circuits. (Default: 60)
  • reset_bw_ipv4_changes = {on, off} — whether or not to reset the bandwidth measurements when the relay's IP address changes. if it changes, we only consider results for the relay that we obtained while the relay was located at its most recent IP address. (Default: off)
  • reset_bw_ipv6_changes = off — NOT implemented for IPv6. (yes, it just says that. that's the whole thing. 😭)

🦋 paths 🦋

when sbws is run as a system service, ~/.sbws is changed to /var/lib/sbws. noted bestie ✨

  • sbws_home = STR — sbws home directory. (Default: ~/.sbws)
  • datadir = STR — directory where sbws stores temporal bandwidth results files. (Default: ~/.sbws/datadir)
  • v3bw_dname = STR — directory where sbws stores the bandwidth list files. these are the files to be read by the Tor Directory Authorities. (Default: ~/.sbws/v3bw)
  • v3bw_fname = STR — file names of the bandwidth list files. the latest bandwidth file is symlinked by latest.v3bw
  • state_fname = STR — file path to store the timestamp when the scanner was last started. (Default: ~/.sbws/state.dat)
  • log_dname = STR — directory where to store log files when logging to files is enabled. (Default: ~/.sbws/log)

💜 destinations 💜

you are required to set at least one destination for the scanner to run. it's recommended to set several destinations so the scanner can keep going if one of them fails — like having multiple backup besties, we love resilience 💅

  • STR = {on, off} — the name of a destination. it's a name for the Web server from where to download or upload data in order to measure bandwidths.
  • usability_test_interval = INT — how often to check if a destination is usable (Default: 300)

🧚 destinations.STR 🧚

  • url = STR — the URL to the destination. it must include a file path and use https, except for 127.0.0.1 which accepts http so you can run the integration tests. 🫶
  • verify = BOOL — whether or not to verify the destination certificate. (Default: True)
  • country = STR — ISO 3166-1 alpha-2 country code. use ZZ if the destination URL is a domain name and it's in a CDN.

🔥 tor 🔥

when sbws is run as a system service, ~/.sbws/tor is replaced by /run/sbws/tor. yes, things move around when systemd gets involved, that's just the lore 💀

  • datadir = STR — sbws' owned tor directory. (Default: ~/.sbws/tor)
  • control_socket = STR — sbws's owned tor control socket file. (Default: ~/.sbws/tor/sbws/control)
  • pid = STR — sbws's owned tor pid file. (Default: ~/.sbws/tor/sbws/tor.pid)
  • log = STR — sbws's owned tor directory log files. (Default: ~/.sbws/tor/log)
  • external_control_port = INT — tor control port to connect to. useful to run integration tests with chutney. (Default: not set. if set, it takes preference over the control socket)
  • extra_lines = — sbws's tor extra configuration. (Default: None)

👑 scanner 👑

  • nickname = STR — a human-readable string with chars in a-zA-Z0-9 to identify the scanner. (Default: IDidntEditTheSBWSConfig)
  • country = STR — ISO 3166-1 alpha-2 country code. (Default: AA, a non existing country to detect it was not edited)
  • download_toofast = INT — limits on what download times are too fast/slow/etc. (Default: 1)
  • download_min = INT — limits on what download times are too fast/slow/etc. (Default: 5)
  • download_target = INT — limits on what download times are too fast/slow/etc. (Default: 6)
  • download_max = INT — limits on what download times are too fast/slow/etc. (Default: 10)
  • num_rtts = INT — how many RTT measurements to make. (Default: 0)
  • num_downloads = INT — number of downloads with acceptable times we must have for a relay before moving on. (Default: 5)
  • initial_read_request = INT — the number of bytes to initially request from the server. (Default: 16384)
  • measurement_threads = INT — how many measurements to make in parallel. (Default: 3)
  • min_download_size = INT — minimum number of bytes we should ever try to download in a measurement. (Default: 1)
  • max_download_size = INT — maximum number of bytes we should ever try to download in a measurement. (Default: 1073741824) — and 1073741824 == 1 GiB in case the number was giving you nothing 🫠
  • upload = BOOL — force upload instead of download even when consensus parameter bwscanner_cc isn't 2. (Default: False)
  • http_post_initial_bytes = INT — the number of bytes to initially POST to the server. (Default: 16384)

🍓 relayprioritizer 🍓

  • measure_authorities = {on, off} — whether or not to measure authorities. (Default: off)
  • fraction_relays = FLOAT — the target fraction of best priority relays we would like to return. 0.05 is 5%. in a 7000 relay network, 5% is 350 relays. (Default: 0.05)
  • min_relays = INT — the minimum number of best priority relays we are willing to return. (Default: 50)

🧹 cleanup 🧹

  • data_files_compress_after_days = INT — after this many days, compress data files. (Default: 29)
  • data_files_delete_after_days = INT — after this many days, delete data files. (Default: 57)
  • v3bw_files_compress_after_days = INT — after this many days, compress v3bw files. (Default: 1)
  • v3bw_files_delete_after_days = INT — after this many days, delete v3bw files. (Default: 7)

📝 logging 📝

  • to_file = {yes, no} — whether or not to log to a rotating file the directory paths.log_dname. (Default: yes)
  • to_stdout = {yes, no} — whether or not to log to stdout. (Default: yes)
  • to_syslog = {yes, no} — whether or not to log to syslog. (Default: no) NOTE that when sbws is launched by systemd, stdout goes to journal and syslog.
  • to_file_num_backups = INT — if logging to file, how many backups to keep. if zero or max bytes is zero, never rotate the log file. (Default: 50)
  • level = {debug, info, warning, error, critical} — level to log at. (Default: debug)
  • to_file_level = {debug, info, warning, error, critical} — level to log at when using files. (Default: debug)
  • to_stdout_level = {debug, info, warning, error, critical} — level to log at when using stdout. (Default: info)
  • to_syslog_level = {debug, info, warning, error, critical} — level to log at when using syslog. (Default: info)
  • format = STR — format string to use when logging. (Default: %(asctime)s %(module)s[%(process)s]: <%(levelname)s> %(message)s)
  • to_stdout_format = STR — format string to use when logging to stdout. (Default: ${format})
  • to_syslog_format = STR — format string to use when logging to syslog. (Default: %(module)s[%(process)s]: <%(levelname)s> %(message)s)
  • to_file_format = STR — format string to use when logging to files. (Default: %(asctime)s %(levelname)s %(threadName)s %(filename)s:%(lineno)s - %(funcName)s - %(message)s)

⭐ EXAMPLES ⭐

here's an example destinations section, copy-paste ready, no gatekeeping 💖

[scanner]
nickname = Manual
country = US

[destinations]
foo = on
bar = on
baz = off

[destinations.foo]
# using HTTP
url = http://example.org/sbws.bin
country = ZZ
verify = False

[destinations.bar]
# using HTTPS
url = https://example.com/data
country = SN

[destinations.baz]
# this will be ignored
url = https://example.net/ask/stan/where/the/file/is.exe
country = TH

🌸 FILES 🌸

  • $HOME/.sbws.ini — default sbws user configuration path.

any other path to the configuration file can be specified using the sbws argument -c. so you're not locked in bestie, you have options 🫶

💫 SEE ALSO 💫

sbws (1), https://tpo.pages.torproject.net/network-health/sbws

🙈 BUGS 🙈

please report bugs at https://gitlab.torproject.org/tpo/network-health/sbws/-/issues/. do it, they want to know 👑

💜 Author 💜

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

CC0

ok that's the whole page, you made it to the end and you ate fr fr 💅✨

this was sbws.ini(5) from sbws 2.2.0, dated Oct 17, 2025. periodt. 🦋

📦 where this page comes from