man_sbws.rst 3.07 KB
Newer Older
juga's avatar
juga committed
1
2
Simple Bandwidth Scanner - SBWS(1)
===================================
juga's avatar
juga committed
3
4
5
6
7
8

SYNOPSIS
--------

sbws [**Optional arguments**] [**Positional arguments**]

juga's avatar
juga committed
9
10
11
sbws [**-h**] [**--version**]
[**--log-level** {**debug,info,warning,error,critical**}]
[**-c** CONFIG] {**cleanup,scanner,generate,init,stats**}
juga's avatar
juga committed
12
13
14
15
16
17
18

DESCRIPTION
-----------

Tor bandwidth scanner that generates bandwidth measurements files to be read by
the Directory Authorities.

19
20
21
The **scanner** requires a configuration file (see **sbws.ini** (5)) with a
with a '[destinations]' section.

22
23
**sbws** can be run a python script or a system service.
The later is recommended.
juga's avatar
juga committed
24

25
26
27
28
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.

juga's avatar
juga committed
29
30
31
32
33
34
35
36
OPTIONS
-------

Positional arguments
~~~~~~~~~~~~~~~~~~~~

{**cleanup,scanner,generate,init,stats**}

juga's avatar
juga committed
37
38
39
These arguments can have additional optional arguments.
To obtain information about them, run: 'sbws <positional argument> --help'.

juga's avatar
juga committed
40
41
42
43
44
45
46
Optional arguments
~~~~~~~~~~~~~~~~~~

-h, --help
   Show help message and exit.

--version
juga's avatar
juga committed
47
   Show **sbws** version and exit.
juga's avatar
juga committed
48
49

--log-level {debug,info,warning,error,critical}
juga's avatar
juga committed
50
   Override the sbws log level (default: info).
juga's avatar
juga committed
51

juga's avatar
juga committed
52
-c CONFIG, --config CONFIG
juga's avatar
juga committed
53
   Path to a custom configuration file.
juga's avatar
juga committed
54
55
56
57

EXAMPLES
--------

58
sbws scanner
juga's avatar
juga committed
59
    Run the scanner using **sbws** defaults.
60

juga's avatar
juga committed
61
sbws -c ~/.sbwsrc scanner
juga's avatar
juga committed
62
    Run the scanner using the configuration file in `~/.sbwsrc`
juga's avatar
juga committed
63
64

sbws --log-level debug generate
juga's avatar
juga committed
65
    Generate v3bw file in the default v3bw directory.
juga's avatar
juga committed
66
67

sbws cleanup
juga's avatar
juga committed
68
    Cleanup datadir and v3bw files older than XX in the default v3bw directory.
juga's avatar
juga committed
69
70
71
72

FILES
-----

juga's avatar
juga committed
73
74
75
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.
juga's avatar
juga committed
76

juga's avatar
juga committed
77
78
79
**$HOME/.sbws.ini** or **/etc/sbws/sbws.ini**
   Location where **sbws** searchs for a custom configuration file, when the
   option **--config** is not provided.
juga's avatar
juga committed
80

juga's avatar
juga committed
81
82
83
**$HOME/.sbws** or **/var/lib/sbws**
   Location where **sbws** writes/reads measurement data files,
   bandwidth list files and **tor** process data.
84

juga's avatar
juga committed
85
   Under this directory, **sbws** creates the following subdirectories:
86

juga's avatar
juga committed
87
88
89
90
    datadir
       Raw results generated by the ``sbws scanner``.
       Other commands (such as ``generate`` and ``stats``) read results from
       this directory.
91

juga's avatar
juga committed
92
93
94
    log
       Log files generated by ``sbws``, when logging to a file is configured
       (see **sbws.ini**).
95

juga's avatar
juga committed
96
97
98
99
100
101
102
103
104
105
    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.
juga's avatar
juga committed
106

juga's avatar
juga committed
107
108
109
SEE ALSO
---------

juga's avatar
juga committed
110
**sbws.ini** (5), https://sbws.readthedocs.org,
juga's avatar
juga committed
111
112
https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt,
**tor** (1).
juga's avatar
juga committed
113
114
115
116

BUGS
----

juga's avatar
juga committed
117
Please report bugs at https://gitlab.torproject.org/tpo/network-health/sbws/-/issues/.