README.md 6.25 KB
Newer Older
1
# Readme
Matt Traudt's avatar
Matt Traudt committed
2

Matt Traudt's avatar
Matt Traudt committed
3
4
[![Build Status](https://travis-ci.org/pastly/simple-bw-scanner.svg?branch=master)](https://travis-ci.org/pastly/simple-bw-scanner)

juga's avatar
juga committed
5
`simple-bw-scanner` (also called `sbws`) is a Tor bandwidth scanner that
juga's avatar
juga committed
6
7
produces bandwidth measurements files to be used by Directory Authorities.

Matt Traudt's avatar
Matt Traudt committed
8
The scanner builds two hop circuits consisting of the relay being measured and
juga's avatar
juga committed
9
10
11
12
13
14
a fast exit. Over these circuits it measures RTT and bandwidth.

**WARNING**: This software is *only* intended to be run by Tor directory
authorities or researches using a test Tor network, chutney or shadow.
Please, do not run this software otherwise, since the measurements would not be
used by Tor and would only create more traffic in the Tor network.
15

16
17
18
See ./INSTALL.rst) for install instructions,
[./DEPLOY.rst](./DEPLOY.rst) for deploy instructions,
[./CONTRIBUTING](./CONTRIBUTING.rst) for contribution guidelines.
19

20
21
More extensive documentation can be found in the ./docs directory,
also online at https://sbws.readthedocs.io and
Matt Traudt's avatar
Matt Traudt committed
22
23
24
25
26
27
28
29
30
31
32
33
34
35
[this onion service](http://d7pxflytfsmz6uh3x7i2jxzzwea6nbpmtsz5tmfkcin5edapaig5vpyd.onion/)
([v2](http://sdmb3rfvp3wadu6y.onion/)).

## Layout of the sbws repo

- `docs/` the source of the sbws documentation website.
- `sbws/` the source code for sbws.
- `sbws/core/` each file contains code specific to a single sbws command.
- `sbws/lib/` complex data structures and classes useful to one or more sbws
  commands. If you're making a new class, it probably belongs here.
- `sbws/util/` simplier, "make life easier" collections of functions.
- `scripts/maint/` scripts for **maint**aining sbws and doing administrative
  things like regenerating the website or updating the AUTHORS file.
- `scripts/tools/` misc. scripts for users of sbws.
36
37
38
39
  performing tests with them.
- `tests/unit/` simple little tests that don't require Tor to be running
- `tests/integration/` more complex tests and/or tests that require Tor to be running
- `tests/testnets/` scripts and code for running mini Tor networks locally
40

41
42
## Boring things

43
44
### Versioning

45
46
47
48
This project follows [semantic versioning][] and thus every major version has
the potential for breaking changes. You can find information about what those
are at the following places.

49
- In the CHANGELOG
50
51
52

[semantic versioning]: https://semver.org/

Matt Traudt's avatar
Matt Traudt committed
53
54
55
56
57
In addition to the overall semantic version for sbws as a whole, there is a
simple integer version for the format in which results are stored.
Incrementing this integer requires a major version change for sbws. (Note that
the reverse is **not** true: a major sbws version change does not require the
integer version for the result format to change)
58

Matt Traudt's avatar
Matt Traudt committed
59
60
61
62
63
64
65
66
67
68
69
70
**Note**: In semantic versioning, "3.4.1-dev" comes **before** "3.4.1". With
this in mind and assuming the current version is "3.4.1-dev": in the last few
commits leading up to a new release, the version will be updated to

- "3.4.1" if only bug fixes
- "3.5.0" if bug fixes and/or backwards-compatible additions/changes
- "4.0.0" if bug fixes and/or backwards-compatible additions/changes and/or
  backwards-**in**compatible additions/changes

Say the version is updated to "3.5.0". The commit **immediately** after the
tagged release should update the version to "3.5.1-dev".

71
72
73
74
75
76
77
**Note**: Before version 1.0.0, we will make an effort to follow semver with a
prepended "0.". For example, "0.2.3" to "0.3.0" probably had a major breaking
change. However, we don't promise this will be followed well. Only trust the
semantic meaning of version numbers when they have reached 1.0.0. Don't worry,
we'll be 1.0.0 before we expect a full deployment on the real Tor network.
(Oh god please don't make me eat my words).

Matt Traudt's avatar
Matt Traudt committed
78
79
80
81
To the best of my knowledge, everything said in this section except our
conventions regarding version bump commit timing is standard semantic
versioning and spelled out in the [link above][semantic versioning].

82
83
84
85
86
87
88
89
### The public API for sbws

As required by semantic versioning, the public API for sbws will not change
without a major version bump. The public API is

- **The available configuration options and their defaults**. New options may
  be added without a major version bump, but no options will be removed, nor
will defaults be drastically changed. Examples of drastic changes to defaults
Matt Traudt's avatar
Matt Traudt committed
90
91
92
93
94
95
include obvious things like changing the default URL for the file to download
or a location for data storage, but also more subjective things, such as
increasing the target download time significantly (6s to 60s). Examples of an
insignificant change include changing the default client nickname. Rule of
thumb: if it is likely to affect results or sbws behavior significantly, it is
a major change.
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

- **The name and function of commands**. The command you run to perform certain
  actions will not change in a backward incompatible way without a major
version change. For example to generate a v3bw file you will always run `sbws
generate` unless there is a major version bump and the release notes indicate
the command has changed.

- **The format of output**. Results (stored in `~/.sbws/datadir` by default)
  will not change their format in a backward incompatible way without both a
major version bump and a bump in the result version integer. The v3bw file
generated with `sbws generate` will not change its format without a major
version bump. *Log lines and the output of `sbws stats` are exceptions to this
rule*.

- **NOT the name, location, signature, or existance of python functions**. Sbws
  is meant to be ran as a standalone program. It is not at all meant to be
treated or used like a library. Users of sbws do *not* need an understanding of
how its code is laid out. Therefore the code may change drastically without a
major version bump as long as the way users interact with it does not change in
a backward incompatible way.

117
118
## The `.sbws` directory

juga's avatar
juga committed
119
By default is `~/.sbws`.
120
121
122

In this directory you will find

123
- `datadir/` Once your sbws scanner has started gathering results, it will dump
124
125
  them into this directory. Other sbws commands (such as generate and stats)
  read results from the files in this directory.
126
127
128
- `log/` If configured, this directory stores logs generated by all the sbws
  commands in rotating log files.
- `v3bw/` This directory stores the v3bw files created with `sbws generate`.
129
130
- `state.dat` A file for storing state needed between sbws commands. See its
  documentation for more information.