Commit 524e263c authored by Matt Traudt's avatar Matt Traudt
Browse files

Touchup faq and glossary

parent 70eff63a
......@@ -17,4 +17,4 @@ help:
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
......@@ -4,40 +4,32 @@ Frequently Asked Questions (FAQ)
.. note:: even thought this questions should be answered by reading the
:doc:`specification`, here the answers should be short and clear.
What is a bandwidth authority?
-----------------------------------
.. todo:: see :ref:`XX`
A server that runs ``sbws scanner``, the bandwidth scanner that performs the
measurements. It can run on the same machine as a directory authority or
somehow send its results to it.
.. note:: You may also enjoy the :doc:`glossary`.
How many hops are the circuits used to perform the measurements?
------------------------------------------------------------------
.. todo:: see :ref:`XX`
Two hops: the relay to be measured and the helper relay.
Two hops: the relay to be measured and the :term:`helper relay`.
How are relays selected to be measured?
---------------------------------------
.. todo:: see :ref:`prioritization`
What is a helper relay?
-----------------------
.. todo:: see :ref:`XX`
The :term:`sbws scanner` periodically refreshes its idea for what relays should
be measured next. It prioritizese the measurement of relays that do not have
recent results. In this way, relays that have just joined the network or have
just come back online after a many-day period of being offline will be measured
before relays that have been online constantly.
Is it the sbws scanner or server that gives the v3bw files to the directory authority?
Is it the sbws scanner or server that gives the v3bw file to the directory authority?
-------------------------------------------------------------------------------------
Technically, neither.
In the suggested setup, the machine running ``sbws scanner`` continuously will
also periodically run ``sbws generate`` to produce a v3bw file for the
directory authority to read.
In the suggested setup, the machine running :term:`sbws scanner` continuously
will also periodically run :term:`sbws generate` to produce a :term:`v3bw file`
for the :term:`bandwidth authority` to read.
.. todo:: see :ref:`XX`
......@@ -45,30 +37,32 @@ directory authority to read.
Is it the sbws scanner or server that I need to run close to a fast relay?
-------------------------------------------------------------------------
The sbws server.
.. todo:: see :ref:`XX`
The :term:`sbws server`.
Why doesn't sbws just use a web/file server instead of custom software?
-----------------------------------------------------------------------
To lower protocol overhead and to allow sbws scanners to request a wide range of
bytes.
To lower protocol overhead and to allow :term:`sbws scanners <sbws scanner>` to
request a wide range of bytes.
Sbws essentially has no overhead, with only about 70 bytes used in a handshake
at the beginning of each connection. A connection can be used to perform
multiple measurements of one relay.
At the time of writing, sbws scanners are allowed to request from the server
between 1 byte and 1,073,741,824 bytes (1 GiB). That's a lot of possibilities
and a ton of storage space.
At the time of writing, sbws scanners are allowed to request from the
:term:`server <sbws server>` between 1 byte and 1,073,741,824 bytes (1 GiB).
That's a lot of possibilities and a ton of storage space.
.. todo:: see :ref:`XX`
.. todo::
Why is there authentication between sbws clien and sbws server?
---------------------------------------------------------------
Look more into the viability of using an HTTP(S) server using HTTP basic
authentication and range requests to control how many bytes to download.
Determine if many requests (and therefore measurements) can be made over a
single stream. Determine how much overhead HTTP adds and make a judgement
call on whether it is worth it.
So random people on the Internet cannot discover an sbws server and ask it to
repeatedly send large amounts of data or otherwise abuse it.
Why is there authentication between sbws scanner and sbws server?
-----------------------------------------------------------------
.. todo:: see :ref:`XX`
So random people on the Internet cannot discover an :term:`sbws server` and ask
it to repeatedly send large amounts of data or otherwise abuse it.
......@@ -3,17 +3,45 @@ Glossary
.. glossary::
directory authority
One of the trusted entities in the Tor network. Calculates a consensus
with the other directory authorities about what relays are running and
much much more.
bandwidth authority
The server that runs the scanner client, ``sbws client``
A :term:`directory authority` that measures and votes about Tor relay
bandwidths. In the context of sbws, it performs measurements with
:term:`sbws scanner` and creates :term:`v3bw file <v3bw files>`
periodically with :term:`sbws generate`
sbws client
The ``sbws`` implementation that perform the measurements
sbws scanner
The sbws command that a :term:`bandwidth authority` runs continuously
to gather information about how fast Tor relays are. The results from
this process are used by :term:`sbws generate` to generate
:term:`v3bw files <v3bw file>`.
sbws server
The ``sbws`` implementation that serves data used to measure the bandwidth
The sbws command that runs as part of a :term:`helper`. :term:`sbws
scanners <sbws scanner>` connect to sbws servers to perform measurements.
helper
The combination of a :term:`helper relay` and :term:`sbws server`,
ideally running on the same machine.
helper relay
The exit relay used by ``sbws client`` circuits to obtain data from the ``sbws server``
The Tor relay that allows exiting to a nearby :term:`sbws server`. It
does not need to be a relay with the Exit flag.
directory authority
See XXX
sbws generate
The sbws command that a :term:`bandwidth authority` runs periodically
to generate a new :term:`v3bw file` from results gathered by
:term:`sbws scanner`.
v3bw file
The file generated by :term:`sbws generate` that a :term:`bandwidth
authority` reads to vote about how fast relays are.
.. literalinclude:: v3bw.txt
:caption: A v3bw file
.. glossary::
1524159868
version=0.1.0
node_id=$1BA71540E05D18401B65B553C35DA71992B9E488 bw=6941170 nick=exit2 rtt=20 time=1524107856
node_id=$189442066BEF15F777738E4E063B7BE0285EA0D9 bw=6855121 nick=exit3 rtt=19 time=1524107855
node_id=$076697F1272A92110AB82226699E62C4EFD49766 bw=6810514 nick=relay4 rtt=20 time=1524107855
node_id=$57BD9518CCC40874D969F0784922EF8B89EB9707 bw=6693692 nick=relay7 rtt=20 time=1524107837
node_id=$B5B33BCBC8C779BFE7B319E0CC3EA6E52EA355EA bw=6653275 nick=relay3 rtt=38 time=1524107847
node_id=$514326DD0EA15A41F1E7840C421A06CCCB2E39FA bw=6614808 nick=exit1 rtt=20 time=1524107837
node_id=$4E5FBF937A4C1D4F9211780BF700E70E30004910 bw=6593946 nick=relay1 rtt=19 time=1524107855
node_id=$D17B78F14F66F9F29686B37A78B77F6AC17DCE92 bw=6483024 nick=relay6 rtt=24 time=1524107848
node_id=$883505B618A0F14EE6136F1451CD4F00760C105F bw=6257421 nick=relay5 rtt=20 time=1524107865
node_id=$654E99AF0EAFA05DCD576C8607F15F3B076C53C8 bw=6069373 nick=relay2 rtt=19 time=1524107860
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