commit aa8807d3064a88b6b489373bd65ad9310a59beea Author: teor <teor@torproject.org> Date: Mon Jan 14 11:27:38 2019 +1000 bandwidth: Add sbws and Tor versions where required --- bandwidth-file-spec.txt | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt index 05d1f40..e3a744f 100644 --- a/bandwidth-file-spec.txt +++ b/bandwidth-file-spec.txt @@ -59,9 +59,8 @@ All Tor versions can consume format version 1.0.0. All Tor versions can consume format version 1.1.0 and later, - but they warn on additional header Lines. - [TODO: this might be fixed, and if it is fixed should be said which - version of Tor] + but Tor versions earlier than 0.3.5.1-alpha warn if the header + contains any KeyValue lines after the Timestamp. 2. Format details @@ -95,7 +94,8 @@ KeyValue ::= Keyword "=" Value Value ::= ArgumentCharValue+ ArgumentCharValue ::= any printing ASCII character except NL and SP. - Terminator ::= "=====" + Terminator ::= "=====" or "====" + Note: sbws versions 0.1.0 to 1.0.2 used a 4-character terminator. Timestamp ::= Int Bandwidth ::= Int MasterKey ::= a base64-encoded Ed25519 public key, with @@ -105,12 +105,13 @@ Note that key_value and value are defined in Tor directory protocol with different formats to KeyValue and Value here. - All Lines in the file MUST be 510 characters or less, to allow for the - trailing newline and NULL characters. - The previous limit was 254 characters in Tor 0.2.6.2-alpha and - earlier. - The parser MAY ignore longer Lines. - [TODO: Change this restriction in 1.1.0 or later] + Tor versions earlier than 0.3.5.1-alpha require all lines in the file + to be 510 characters or less. The previous limit was 254 characters in + Tor 0.2.6.2-alpha and earlier. Parsers MAY ignore longer Lines. + + Note that directory authorities are only supported on the two most + recent stable Tor versions, so we expect that line limits will be + removed after Tor 0.4.0 is released in 2019. 2.2. Header List format @@ -305,7 +306,7 @@ It consists of: In version 1.0.0, Header List ends when the first relay bandwidth is found conforming to the next section. - Implementations of version 1.1.0 SHOULD include this Line. + Implementations of version 1.1.0 and later SHOULD include this Line. 2.3. Relays' Bandwidth List format @@ -325,9 +326,6 @@ If a parser does not recognize any extra material in a RelayLine, the extra material MUST be ignored. Each RelayLine MUST include the following KeyValue pairs: -In version 1.0.0, node_id MUST NOT be at the end of the Line. -In version 1.1.0, the KeyValue can be in any arbitrary order. -[TODO: list of Tor version that support it, when it's done] "node_id=" hexdigest @@ -335,6 +333,10 @@ In version 1.1.0, the KeyValue can be in any arbitrary order. The fingerprint for the relay's RSA identity key. + Note: In bandwidth files read by Tor versions earlier than + 0.3.4.1-alpha, node_id MUST NOT be at the end of the Line. + These authority versions are no longer supported. + "master_key_ed25519=" MasterKey [Zero or one time.] @@ -568,8 +570,8 @@ earliest_bandwidth=2018-04-16T15:13:26 bw=380 error_circ=0 error_misc=0 error_stream=1 master_key_ed25519=YaqV4vbvPYKucElk297eVdNArDz9HtIwUoIeo0+cVIpQ nick=Test node_id=$68A483E05A2ABDCA6DA5A3EF8DB5177638A27F80 rtt=380 success=1 time=2018-05-08T16:13:26 bw=189 error_circ=0 error_misc=0 error_stream=0 master_key_ed25519=a6a+dZadrQBtfSbmQkP7j2ardCmLnm5NJ4ZzkvDxbo0I nick=Test2 node_id=$96C15995F30895689291F455587BD94CA427B6FC rtt=378 success=1 time=2018-05-08T16:13:36 -A.3. Generated by sbws version 1.X.X -[TODO: change the version of sbws that generates this when it is implemented] +A.3. Generated by sbws version 1.0.3 + 1523911758 version=1.2.0 latest_bandwidth=2018-04-16T20:49:18 @@ -582,8 +584,7 @@ number_consensus_relays=6436 number_eligible_relays=6000 percent_eligible_relays=93 software=sbws -software_version=1.X.X -[TODO: change the version of sbws that generates this when it is implemented] +software_version=1.0.3 ===== bw=38000 bw_mean=1127824 bw_median=1180062 desc_avg_bw=1073741824 desc_obs_bw_last=17230879 desc_obs_bw_mean=14732306 error_circ=0 error_misc=0 error_stream=1 master_key_ed25519=YaqV4vbvPYKucElk297eVdNArDz9HtIwUoIeo0+cVIpQ nick=Test node_id=$68A483E05A2ABDCA6DA5A3EF8DB5177638A27F80 rtt=380 success=1 time=2018-05-08T16:13:26 bw=1 bw_mean=199162 bw_median=185675 desc_avg_bw=409600 desc_obs_bw_last=836165 desc_obs_bw_mean=858030 error_circ=0 error_misc=0 error_stream=0 master_key_ed25519=a6a+dZadrQBtfSbmQkP7j2ardCmLnm5NJ4ZzkvDxbo0I nick=Test2 node_id=$96C15995F30895689291F455587BD94CA427B6FC rtt=378 success=1 time=2018-05-08T16:13:36 @@ -602,8 +603,7 @@ number_consensus_relays=6436 number_eligible_relays=2960 percent_eligible_relays=46 software=sbws -software_version=1.X.X -[TODO: change the version of sbws that generates this when it is implemented] +software_version=1.0.3 ===== B. Scaling bandwidths