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

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

Tor bandwidth scanner configuration file.

9
10
**sbws** (1) ``scanner`` command requires a configuration file with the
"[scanner]", "[destinations]" "[destination.<name>]" sections.
juga's avatar
juga committed
11

12
There must be at least one "[destination.<name>]".
juga's avatar
juga committed
13

14
See an **EXAMPLES** below for a minimal configuration.
juga's avatar
juga committed
15

juga's avatar
juga committed
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
SECTIONS
---------

general
  data_period = INT
    Days into the past that measurements are considered valid. (Default: 5)
  http_timeout = INT
    Timeout in seconds to give to the python Requests library. (Default: 10)
  circuit_timeout = INT
    Timeout in seconds to create circuits. (Default: 10)
  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: on)
  reset_bw_ipv6_changes = off
    NOT implemented for IPv6.

paths
35
36
37
38

  When **sbws** is run as a system service, `~/.sbws` is changed to
  `/var/lib/sbws`.

juga's avatar
juga committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
  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 ``latests.v3bw``
  started_filepath = STR
    File path to store the timestamp when the scanner was last started.
    (Default: ~/.sbws/started_at)
  log_dname = STR
    Directory where to store log files when logging to files is enabled.
    (Default ~/.sbws/log)

destinations
59
60
61
62
63

  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.

juga's avatar
juga committed
64
65
66
67
  STR = {on, off}
    Name of destination. It is a name for the Web server from where to
    download files in order to measure bandwidths.

juga's avatar
juga committed
68
69
70
  usability_test_interval = INT
    How often to check if a destination is usable

juga's avatar
juga committed
71
72
destinations.STR
  url = STR
juga's avatar
juga committed
73
74
    The URL to the destination. It must include a file path.
    It can use both http or https.
75
76
77
  verify = BOOL
    Whether or not to verify the destination certificate.
    (Default: True)
78
79
80
  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.
juga's avatar
juga committed
81

juga's avatar
juga committed
82
tor
83
84
85
86

  When **sbws** is run as a system service `~/.sbws/tor` is replaced by
  `/run/sbws/tor`.

juga's avatar
juga committed
87
88
89
90
  datadir = STR
    sbws' owned tor directory. (Default: ~/.sbws/tor)
  control_socket = STR
    sbws's owned tor control socket file.
91
    (Default: ~/.sbws/tor/sbws/control)
juga's avatar
juga committed
92
  pid = STR
93
    sbws's owned tor pid file. (Default: ~/.sbws/tor/sbws/tor.pid)
juga's avatar
juga committed
94
95
96
97
98
99
100
101
102
  log = STR
    sbws's owned tor directory log files. (Default: ~/.sbws/tor/log)
  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)
103
104
105
  country = STR
    ISO 3166-1 alpha-2 country code.
    (Default: AA, a non existing country to detect it was not edited)
juga's avatar
juga committed
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
  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: 10)
  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) 1073741824 == 1 GiB

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
  stale_days = INT
    After this many days, compress data files. (Default: 10)
  rotten_days = INT
    After this many days, delete data files. (Default: 90)

logging
  to_file = {yes, no}
    Whether or not to log to a rotating file the directory paths.log_dname.
    (Default: no)
  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)
154
155
    NOTE that when sbws is launched by systemd, stdout goes to journal and
    syslog.
juga's avatar
juga committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
  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)
  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: info)
  to_file_level = {debug, info, warning, error, critical}
    Level to log at when using files. (Default: info)
  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] [%(name)s] [%(levelname)s] %(message)s)
  to_file_format = STR
    Format string to use when logging to files. (Default: $format)
  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)

juga's avatar
juga committed
182
183
184
185
186
EXAMPLES
--------

Example ``destinations`` section::

187
188
189
190
    [scanner]
    nickname = Manual
    country = US

juga's avatar
juga committed
191
192
193
194
195
196
197
198
    [destinations]
    foo = on
    bar = on
    baz = off

    [destinations.foo]
    # using HTTP
    url = http://example.org/sbws.bin
199
200
    country = ZZ
    verify = False
juga's avatar
juga committed
201
202
203
204

    [destinations.bar]
    # using HTTPS
    url = https://example.com/data
205
    country = SN
juga's avatar
juga committed
206
207
208
209

    [destinations.baz]
    # this will be ignored
    url = https://example.net/ask/stan/where/the/file/is.exe
210
    country = TH
juga's avatar
juga committed
211

juga's avatar
juga committed
212
213
214
215
FILES
-----

$HOME/.sbws.ini
juga's avatar
juga committed
216
   Default ``sbws`` user configuration path.
juga's avatar
juga committed
217

218
219
Any other path to the configuration file can be specified using the
``sbws`` argument ``-c``
juga's avatar
juga committed
220
221
222
223
224
225
226
227
228

SEE ALSO
---------

**sbws** (1), https://sbws.readthedocs.org.

BUGS
----

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