[tor-commits] [torspec/master] bandwidth-file: Add summaries for format version 1.3.0 and 1.4.0

[teor at torproject.org]

commit 41a520605361451b3da21b6619a4ea5c63b9332d
Author: teor <teor at torproject.org>
Date:   Fri Mar 22 11:46:42 2019 +1000

    bandwidth-file: Add summaries for format version 1.3.0 and 1.4.0
    
    Part of 29754.
---
 bandwidth-file-spec.txt | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt
index 452dc21..5148892 100644
--- a/bandwidth-file-spec.txt
+++ b/bandwidth-file-spec.txt
@@ -52,17 +52,35 @@
   1.2.0 - If there are not enough eligible relays, the bandwidth file
           SHOULD contain a header, but no relays. (To match Torflow's
           existing behaviour.)
+
           Adds new KeyValue Lines to the Header List section with
           statistics about the number of relays included in the file.
           Add new KeyValues to Relay Bandwidth Lines, with different
           bandwidth values (averages and descriptor bandwidths).
 
+  1.3.0 - Adds scanner and destination countries to the header.
+
+  1.4.0 - Adds monitoring KeyValues to the header and relay lines.
+
+          RelayLines for excluded relays MAY be present in the bandwidth
+          file for diagnostic reasons. Similarly, if there are not enough
+          eligible relays, the bandwidth file MAY contain all known relays.
+
+          Diagnostic relay lines SHOULD be marked with vote=0, and
+          Tor SHOULD NOT use their bandwidths in its votes.
+
   All Tor versions can consume format version 1.0.0.
 
   All Tor versions can consume format version 1.1.0 and later,
   but Tor versions earlier than 0.3.5.1-alpha warn if the header
   contains any KeyValue lines after the Timestamp.
 
+  Tor versions 0.4.0.3-alpha, 0.3.5.8, 0.3.4.11, and earlier do not
+  understand "vote=0". Instead, they will vote for the actual bandwidths
+  that sbws puts in diagnostic relay lines:
+    * 1 for relays with "unmeasured=1", and
+    * the relay's measured and scaled bandwidth when "under_min_report=1".
+
 2. Format details
 
   The Bandwidth File MUST contain the following sections:
@@ -242,9 +260,16 @@
       [Zero or one time.]
 
       The percentage of relays in the consensus that SHOULD be
-      included in every generated bandwidth file.  If there are not
-      enough eligible relays, the bandwidth file SHOULD contain a
-      header, but no relays.
+      included in every generated bandwidth file.
+
+      If this threshold is not reached, format versions 1.3.0 and earlier
+      SHOULD NOT contain any relays. (Bandwidth files always include a
+      header.)
+
+      Format versions 1.4.0 and later SHOULD include all the relays for
+      diagnostic purposes, even if this threshold is not reached. But these
+      relays SHOULD be marked so that Tor does not vote on them.
+      See section 1.4 for details.
 
       The minimum percentage is 60% in Torflow, so sbws uses
       60% as the default.
@@ -276,7 +301,8 @@
 
       [Zero or one time.]
 
-      The minimum number of relays to include in the bandwidth file.
+      The minimum number of relays that SHOULD be included in the bandwidth
+      file. See minimum_percent_eligible_relays for details.
 
       This line SHOULD be equal to:
           number_consensus_relays * (minimum_percent_eligible_relays / 100.0)