Touchup faq and glossary

docs/Makefile

@@ -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)

docs/source/faq.rst

@@ -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.

docs/source/glossary.rst

@@ -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::

docs/source/v3bw.txt

+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