commit b52afd654c0f2c5e8e7d273e8e42bd8a1c69f14f Author: juga0 <juga@riseup.net> Date: Thu Mar 14 15:38:38 2019 +0000 chg: docs: document that authorities are not measured and improve a bit the summary about what sbws does. Closes: #29722 --- README.md | 14 +++++++++----- docs/source/how_works.rst | 19 +++++++++++++------ 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 70508da..8c57464 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,17 @@ [](https://travis-ci.org/https://travis-ci.org/torproject/sbws) Simple Bandwidth Scanner (called `sbws`) is a Tor bandwidth scanner that -produces bandwidth files to be used by Directory Authorities. +generates bandwidth files to be used by Directory Authorities. -The scanner builds two hop circuits consisting of the relay being measured and -a fast exit. Over these circuits it measures bandwidth and store the results. +The scanner measures the bandwidth of each relay in the Tor network +(except the directory authorities) by creating a two hops circuit +with the relay. It then measures the bandwidth by downloading data +from a destination Web Server and stores the measurements. -The generator read the measurement results, scales them using torflow's -scaling method and creates the bandwidth file. +The generator read the measurements, aggregates, filters and +scales them using torflow's scaling method. +Then it generates a bandwidth list file that is read +by a directory authority to report relays’ bandwidth in its vote. **WARNING**: This software is intended to be run by researchers using a test Tor network, such as chutney or shadow, or by the Tor bandwidth authorities diff --git a/docs/source/how_works.rst b/docs/source/how_works.rst index c9d10f3..470c55c 100644 --- a/docs/source/how_works.rst +++ b/docs/source/how_works.rst @@ -7,12 +7,19 @@ Running the scanner Overview ~~~~~~~~~ -The :term:`scanner` obtain a list of relays from the Tor network. -It measures the bandwidth of each relay by creating a two hop circuit with the -relay to measure and download data from a :term:`destination` Web Server. -The :term:`generator` creates a :term:`bandwidth list file` that is read -by a :term:`directory authority` and used to report relays' bandwidth in its -vote. +.. The following text is part of the introduction in the README, but rst + formatted. + +The :term:`scanner` measures the bandwidth of each relay in the Tor network +(except the directory authorities) by creating a two hops circuit +with the relay. It then measures the bandwidth by downloading data +from a :term:`destination` Web Server and stores the measurements. + +The :term:`generator` read the measurements, aggregates, filters and +scales them using torflow's scaling method. + +Then it generates a :term:`bandwidth list file` that is read +by a :term:`directory authority` to report relays’ bandwidth in its vote. .. image:: ./images/scanner.svg :height: 200px