man_sbws.ini.rst 7.8 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
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
25
    Timeout in seconds to create circuits. (Default: 60)
juga's avatar
juga committed
26
27
28
29
  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.
30
    (Default: off)
juga's avatar
juga committed
31
32
33
34
  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
  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.
50
51
    The latest bandwidth file is symlinked by ``latest.v3bw``
  state_fname = STR
juga's avatar
juga committed
52
    File path to store the timestamp when the scanner was last started.
53
    (Default: ~/.sbws/state.dat)
juga's avatar
juga committed
54
55
  log_dname = STR
    Directory where to store log files when logging to files is enabled.
56
    (Default: ~/.sbws/log)
juga's avatar
juga committed
57
58

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
  usability_test_interval = INT
69
    How often to check if a destination is usable (Default: 300)
juga's avatar
juga committed
70

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
  log = STR
    sbws's owned tor directory log files. (Default: ~/.sbws/tor/log)
96
97
98
99
  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)
juga's avatar
juga committed
100
101
102
103
104
105
106
  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)
107
108
109
  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
110
111
112
113
114
115
116
117
118
  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
119
    How many RTT measurements to make. (Default: 0)
juga's avatar
juga committed
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
  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
145
  data_files_compress_after_days = INT
juga's avatar
juga committed
146
    After this many days, compress data files. (Default: 10)
147
  data_files_delete_after_days = INT
juga's avatar
juga committed
148
    After this many days, delete data files. (Default: 90)
149
150
151
152
  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)
juga's avatar
juga committed
153
154
155
156

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

juga's avatar
juga committed
191
192
193
194
195
EXAMPLES
--------

Example ``destinations`` section::

196
197
198
199
    [scanner]
    nickname = Manual
    country = US

juga's avatar
juga committed
200
201
202
203
204
205
206
207
    [destinations]
    foo = on
    bar = on
    baz = off

    [destinations.foo]
    # using HTTP
    url = http://example.org/sbws.bin
208
209
    country = ZZ
    verify = False
juga's avatar
juga committed
210
211
212
213

    [destinations.bar]
    # using HTTPS
    url = https://example.com/data
214
    country = SN
juga's avatar
juga committed
215
216
217
218

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

juga's avatar
juga committed
221
222
223
224
FILES
-----

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

227
228
Any other path to the configuration file can be specified using the
``sbws`` argument ``-c``
juga's avatar
juga committed
229
230
231
232
233
234
235
236
237

SEE ALSO
---------

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

BUGS
----

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