.\" Man page generated from reStructuredText.
.
.TH "SBWS.INI" "5" "May 20, 2022" "get_versions()["version"]" "sbws"
.SH NAME
sbws.ini \- Simple Bandwidth Scanner configuration
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.sp
Tor bandwidth scanner configuration file.
.sp
\fBsbws\fP (1) \fBscanner\fP command requires a configuration file with the
"[scanner]", "[destinations]" "[destination.<name>]" sections.
.sp
There must be at least one "[destination.<name>]".
.sp
See an \fBEXAMPLES\fP below for a minimal configuration.
.SH SECTIONS
.INDENT 0.0
.TP
.B general
.INDENT 7.0
.TP
.B data_period = INT
Days into the past that measurements are considered valid. (Default: 5)
.TP
.B http_timeout = INT
Timeout in seconds to give to the python Requests library. (Default: 10)
.TP
.B circuit_timeout = INT
Timeout in seconds to create circuits. (Default: 60)
.TP
.B reset_bw_ipv4_changes = {on, off}
Whether or not to reset the bandwidth measurements when the relay\(aqs 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)
.TP
.B reset_bw_ipv6_changes = off
NOT implemented for IPv6.
.UNINDENT
.UNINDENT
.sp
paths
.INDENT 0.0
.INDENT 3.5
When \fBsbws\fP is run as a system service, \fI~/.sbws\fP is changed to
\fI/var/lib/sbws\fP\&.
.INDENT 0.0
.TP
.B sbws_home = STR
sbws home directory. (Default: ~/.sbws)
.TP
.B datadir = STR
Directory where sbws stores temporal bandwidth results files.
(Default: ~/.sbws/datadir)
.TP
.B 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)
.TP
.B v3bw_fname = STR
File names of the bandwidth list files.
The latest bandwidth file is symlinked by \fBlatest.v3bw\fP
.TP
.B state_fname = STR
File path to store the timestamp when the scanner was last started.
(Default: ~/.sbws/state.dat)
.TP
.B log_dname = STR
Directory where to store log files when logging to files is enabled.
(Default: ~/.sbws/log)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
destinations
.INDENT 0.0
.INDENT 3.5
It is required to set at least one destination for the scanner to run.
It is recommended to set several destinations so that the scanner can
continue if one fails.
.INDENT 0.0
.TP
.B STR = {on, off}
Name of destination. It is a name for the Web server from where to
download files in order to measure bandwidths.
.TP
.B usability_test_interval = INT
How often to check if a destination is usable (Default: 300)
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B destinations.STR
.INDENT 7.0
.TP
.B url = STR
The URL to the destination. It must include a file path.
It can use both http or https.
.TP
.B verify = BOOL
Whether or not to verify the destination certificate.
(Default: True)
.TP
.B country = STR
ISO 3166\-1 alpha\-2 country code.
Use ZZ if the destination URL is a domain name and it is in a CDN.
.UNINDENT
.UNINDENT
.sp
tor
.INDENT 0.0
.INDENT 3.5
When \fBsbws\fP is run as a system service \fI~/.sbws/tor\fP is replaced by
\fI/run/sbws/tor\fP\&.
.INDENT 0.0
.TP
.B datadir = STR
sbws\(aq owned tor directory. (Default: ~/.sbws/tor)
.TP
.B control_socket = STR
sbws\(aqs owned tor control socket file.
(Default: ~/.sbws/tor/sbws/control)
.TP
.B pid = STR
sbws\(aqs owned tor pid file. (Default: ~/.sbws/tor/sbws/tor.pid)
.TP
.B log = STR
sbws\(aqs owned tor directory log files. (Default: ~/.sbws/tor/log)
.TP
.B 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)
.TP
.B extra_lines =
sbws\(aqs tor extra configuration. (Default: None)
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B scanner
.INDENT 7.0
.TP
.B nickname = STR
A human\-readable string with chars in a\-zA\-Z0\-9 to identify the scanner.
(Default: IDidntEditTheSBWSConfig)
.TP
.B country = STR
ISO 3166\-1 alpha\-2 country code.
(Default: AA, a non existing country to detect it was not edited)
.TP
.B download_toofast = INT
Limits on what download times are too fast/slow/etc. (Default: 1)
.TP
.B download_min = INT
Limits on what download times are too fast/slow/etc. (Default: 5)
.TP
.B download_target = INT
Limits on what download times are too fast/slow/etc. (Default: 6)
.TP
.B download_max = INT
Limits on what download times are too fast/slow/etc. (Default: 10)
.TP
.B num_rtts = INT
How many RTT measurements to make. (Default: 0)
.TP
.B num_downloads = INT
Number of downloads with acceptable times we must have for a relay before
moving on. (Default: 5)
.TP
.B initial_read_request = INT
The number of bytes to initially request from the server. (Default: 16384)
.TP
.B measurement_threads = INT
How many measurements to make in parallel. (Default: 3)
.TP
.B min_download_size = INT
Minimum number of bytes we should ever try to download in a measurement.
(Default: 1)
.TP
.B max_download_size = INT
Maximum number of bytes we should ever try to download in a measurement.
(Default: 1073741824) 1073741824 == 1 GiB
.UNINDENT
.TP
.B relayprioritizer
.INDENT 7.0
.TP
.B measure_authorities = {on, off}
Whether or not to measure authorities. (Default: off)
.TP
.B 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)
.TP
.B min_relays = INT
The minimum number of best priority relays we are willing to return.
(Default: 50)
.UNINDENT
.TP
.B cleanup
.INDENT 7.0
.TP
.B data_files_compress_after_days = INT
After this many days, compress data files. (Default: 29)
.TP
.B data_files_delete_after_days = INT
After this many days, delete data files. (Default: 57)
.TP
.B v3bw_files_compress_after_days = INT
After this many days, compress v3bw files. (Default: 1)
.TP
.B v3bw_files_delete_after_days = INT
After this many days, delete v3bw files. (Default: 7)
.UNINDENT
.TP
.B logging
.INDENT 7.0
.TP
.B to_file = {yes, no}
Whether or not to log to a rotating file the directory paths.log_dname.
(Default: yes)
.TP
.B to_stdout = {yes, no}
Whether or not to log to stdout. (Default: yes)
.TP
.B 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.
.TP
.B to_file_max_bytes = INT
If logging to file, how large (in bytes) should the file be allowed to get
before rotating to a new one. 10485760 is 10 MiB. If zero or number of
backups is zero, never rotate the log file. (Default: 10485760)
.TP
.B 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)
.TP
.B level = {debug, info, warning, error, critical}
Level to log at. (Default: debug)
.TP
.B to_file_level = {debug, info, warning, error, critical}
Level to log at when using files. (Default: debug)
.TP
.B to_stdout_level = {debug, info, warning, error, critical}
Level to log at when using stdout. (Default: info)
.TP
.B to_syslog_level = {debug, info, warning, error, critical}
Level to log at when using syslog. (Default: info)
.TP
.B format = STR
Format string to use when logging.
(Default: %(asctime)s %(module)s[%(process)s]: <%(levelname)s> %(message)s)
.TP
.B to_stdout_format = STR
Format string to use when logging to stdout. (Default: ${format})
.TP
.B to_syslog_format = STR
Format string to use when logging to syslog.
(Default: %(module)s[%(process)s]: <%(levelname)s> %(message)s)
.TP
.B 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)
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
Example \fBdestinations\fP section:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH FILES
.INDENT 0.0
.TP
.B $HOME/.sbws.ini
Default \fBsbws\fP user configuration path.
.UNINDENT
.sp
Any other path to the configuration file can be specified using the
\fBsbws\fP argument \fB\-c\fP
.SH SEE ALSO
.sp
\fBsbws\fP (1), \fI\%https://tpo.pages.torproject.net/network\-health/sbws\fP\&.
.SH BUGS
.sp
Please report bugs at \fI\%https://gitlab.torproject.org/tpo/network\-health/sbws/\-/issues/\fP\&.
.SH AUTHOR
Matt Traudt [sirmatt at ksu dot edu], juga [juga at riseup dot net]
.SH COPYRIGHT
CC0
.\" Generated by docutils manpage writer.
.