.\" Man page generated from reStructuredText.
.
.TH "SBWS" "1" "May 20, 2022" "get_versions()["version"]" "sbws"
.SH NAME
sbws \- Simple Bandwidth Scanner
.
.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 SYNOPSIS
.sp
sbws [\fBOptional arguments\fP] [\fBPositional arguments\fP]
.sp
sbws [\fB\-h\fP] [\fB\-\-version\fP]
[\fB\-\-log\-level\fP {\fBdebug,info,warning,error,critical\fP}]
[\fB\-c\fP CONFIG] {\fBcleanup,scanner,generate,init,stats\fP}
.SH DESCRIPTION
.sp
Tor bandwidth scanner that generates bandwidth measurements files to be read by
the Directory Authorities.
.sp
The \fBscanner\fP requires a configuration file (see \fBsbws.ini\fP (5)) with a
with a \(aq[destinations]\(aq section.
.sp
\fBsbws\fP can be run a python script or a system service.
The later is recommended.
.sp
The default locations of the files that \fBsbws\fP reads or generate depend on
on how it is run.
See the section \fBFILES\fP to know which are the default locations.
.SH OPTIONS
.SS Positional arguments
.sp
{\fBcleanup,scanner,generate,init,stats\fP}
.sp
These arguments can have additional optional arguments.
To obtain information about them, run: \(aqsbws <positional argument> \-\-help\(aq.
.SS Optional arguments
.INDENT 0.0
.TP
.B \-h\fP,\fB  \-\-help
Show help message and exit.
.TP
.B \-\-version
Show \fBsbws\fP version and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-level {debug,info,warning,error,critical}
Override the sbws log level (default: info).
.UNINDENT
.INDENT 0.0
.TP
.BI \-c \ CONFIG\fR,\fB \ \-\-config \ CONFIG
Path to a custom configuration file.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.TP
.B sbws scanner
Run the scanner using \fBsbws\fP defaults.
.TP
.B sbws \-c ~/.sbwsrc scanner
Run the scanner using the configuration file in \fI~/.sbwsrc\fP
.TP
.B sbws \-\-log\-level debug generate
Generate v3bw file in the default v3bw directory.
.TP
.B sbws cleanup
Cleanup datadir and v3bw files older than XX in the default v3bw directory.
.UNINDENT
.SH FILES
.sp
In the following list, the first path is the default location when running
\fBsbws\fP as an script, the second path is the default location when running
\fBsbws\fP as a system service.
.INDENT 0.0
.TP
\fB$HOME/.sbws.ini\fP or \fB/etc/sbws/sbws.ini\fP
Location where \fBsbws\fP searches for a custom configuration file, when the
option \fB\-\-config\fP is not provided.
.TP
\fB$HOME/.sbws\fP or \fB/var/lib/sbws\fP
Location where \fBsbws\fP writes/reads measurement data files,
bandwidth list files and \fBtor\fP process data.
.sp
Under this directory, \fBsbws\fP creates the following subdirectories:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B datadir
Raw results generated by the \fBsbws scanner\fP\&.
Other commands (such as \fBgenerate\fP and \fBstats\fP) read results from
this directory.
.TP
.B log
Log files generated by \fBsbws\fP, when logging to a file is configured
(see \fBsbws.ini\fP).
.TP
.B v3bw
Bandwidth files generated by \fBsbws generate\fP\&. These are the files
read by the Tor directory authorities.
.TP
.B tor
Data generated by the \fBtor\fP process launched by \fBsbws\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.TP
\fB$HOME/.sbws/tor\fP or \fB/run/sbws/tor\fP
Location where the \fBtor\fP process launched by \fBsbws scanner\fP stores
temporal files, like Unix domain sockets.
.UNINDENT
.SH SEE ALSO
.sp
\fBsbws.ini\fP (5), \fI\%https://tpo.pages.torproject.net/network\-health/sbws\fP,
\fI\%https://gitweb.torproject.org/torspec.git/tree/bandwidth\-file\-spec.txt\fP,
\fBtor\fP (1).
.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.
.