Commit 46f4812c authored by Matt Traudt's avatar Matt Traudt
Browse files

Update README

parent 93207b81
......@@ -4,14 +4,32 @@
It doesn't get simpler than this, folks.
Run `sbws server` on the same machine as a relay with an exit policy that
allows exiting to itself on a single port. (Notice: it won't get the exit flag)
The scanner builds two hop circuits consisting of the relay being measured and
a fast exit. Over these circuits it measures RTT and download performance.
Run `sbws client` on a well-connected machine on the Internet.
See INSTALL for install instructions. See DEPLOY for deploy instructions. See
LICENSE for license information. See CONTRIBUTING for coding standards and
contribution guidelines.
The scanner builds two hop circuits consisting of the relay being measured and
the helper relay running server.py. Over these circuits it measures RTT and
download performance.
The sbws documentation can be found at [Read the Docs](https://sbws.readthedocs.io)
and
[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.
- `tests/testnets/` scripts and code for running mini Tor networks locally and
performing integration tests with them.
- `tests/` unit tests executed with `pytest` or `tox`.
## Boring things
......@@ -25,13 +43,11 @@ are at the following places.
[semantic versioning]: https://semver.org/
In addition to the overall semantic version for sbws as a whole, there are
simple integer versions for (i) the protocol sbws clients and servers use to
speak to each other, and (ii) the format in which results are stored.
Incrementing either of these version numbers requires a major version change
for sbws. (Note that the reverse is **not** true: a major sbws version change
does not require the integer versions for the wire protocol or result format to
change)
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)
**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
......@@ -64,11 +80,12 @@ 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
include obvious things like flipping any boolean value 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.
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.
- **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
......@@ -83,10 +100,6 @@ 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*.
- **The wire protocol**. The way `sbws client` and `sbws server` speak will not
change in a backward incompatible way without both a major version bump and a
bump in the wire protocol version integer.
- **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
......@@ -94,33 +107,6 @@ 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.
### License
This project is released to the public domain under the CC0 1.0 Universal
license. See LICENSE for more information.
## Documentation
The sbws documentation can be found at [Read the Docs](https://sbws.readthedocs.io)
and
[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.
- `tests/testnets/` scripts and code for running mini Tor networks locally and
performing integration tests with them.
- `tests/` unit tests executed with `pytest` or `tox`.
### Build HTML documentation
pip install -e .[doc]
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment