bandwidth-file-spec.txt 40 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157
  1. Tor Bandwidth File Format
  2. juga
  3. teor
  4. 1. Scope and preliminaries
  5. This document describes the format of Tor's Bandwidth File, version
  6. 1.0.0 and later.
  7. It is a new specification for the existing bandwidth file format,
  8. which we call version 1.0.0. It also specifies new format versions
  9. 1.1.0 and later, which are backwards compatible with 1.0.0 parsers.
  10. Since Tor version 0.2.4.12-alpha, the directory authorities use
  11. the Bandwidth File file called "V3BandwidthsFile" generated by
  12. Torflow [1]. The details of this format are described in Torflow's
  13. README.spec.txt. We also summarise the format in this specification.
  14. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  15. NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
  16. "OPTIONAL" in this document are to be interpreted as described in
  17. RFC 2119.
  18. 1.2. Acknowledgements
  19. The original bandwidth generator (Torflow) and format was
  20. created by mike. Teor suggested to write this specification while
  21. contributing on pastly's new bandwidth generator implementation.
  22. This specification was revised after feedback from:
  23. Nick Mathewson (nickm)
  24. Iain Learmonth (irl)
  25. 1.3 Outline
  26. The Tor directory protocol (dir-spec.txt [3]) sections 3.4.1
  27. and 3.4.2, use the term bandwidth measurements, to refer to what
  28. here is called Bandwidth File.
  29. A Bandwidth File contains information on relays' bandwidth
  30. capacities and is produced by bandwidth generators, previously known
  31. as bandwidth scanners.
  32. 1.4. Format Versions
  33. 1.0.0 - The legacy Bandwidth File format
  34. 1.1.0 - Add a header containing information about the bandwidth
  35. file. Document the sbws and Torflow relay line keys.
  36. 1.2.0 - If there are not enough eligible relays, the bandwidth file
  37. SHOULD contain a header, but no relays. (To match Torflow's
  38. existing behaviour.)
  39. Adds new KeyValue Lines to the Header List section with
  40. statistics about the number of relays included in the file.
  41. Add new KeyValues to Relay Bandwidth Lines, with different
  42. bandwidth values (averages and descriptor bandwidths).
  43. 1.3.0 - Adds scanner and destination countries to the header.
  44. 1.4.0 - Adds monitoring KeyValues to the header and relay lines.
  45. RelayLines for excluded relays MAY be present in the bandwidth
  46. file for diagnostic reasons. Similarly, if there are not enough
  47. eligible relays, the bandwidth file MAY contain all known relays.
  48. Diagnostic relay lines SHOULD be marked with vote=0, and
  49. Tor SHOULD NOT use their bandwidths in its votes.
  50. All Tor versions can consume format version 1.0.0.
  51. All Tor versions can consume format version 1.1.0 and later,
  52. but Tor versions earlier than 0.3.5.1-alpha warn if the header
  53. contains any KeyValue lines after the Timestamp.
  54. Tor versions 0.4.0.3-alpha, 0.3.5.8, 0.3.4.11, and earlier do not
  55. understand "vote=0". Instead, they will vote for the actual bandwidths
  56. that sbws puts in diagnostic relay lines:
  57. * 1 for relays with "unmeasured=1", and
  58. * the relay's measured and scaled bandwidth when "under_min_report=1".
  59. 2. Format details
  60. The Bandwidth File MUST contain the following sections:
  61. - Header List (exactly once), which is a partially ordered list of
  62. - Header Lines (one or more times), then
  63. - Relay Lines (zero or more times), in an arbitrary order.
  64. If it does not contain these sections, parsers SHOULD ignore the file.
  65. 2.1. Definitions
  66. The following nonterminals are defined in Tor directory protocol
  67. sections 1.2., 2.1.1., 2.1.3.:
  68. bool
  69. Int
  70. SP (space)
  71. NL (newline)
  72. KeywordChar
  73. ArgumentChar
  74. nickname
  75. hexdigest (a '$', followed by 40 hexadecimal characters
  76. ([A-Fa-f0-9]))
  77. Nonterminal defined section 2 of version-spec.txt [4]:
  78. version_number
  79. We define the following nonterminals:
  80. Line ::= ArgumentChar* NL
  81. RelayLine ::= KeyValue (SP KeyValue)* NL
  82. HeaderLine ::= KeyValue NL
  83. KeyValue ::= Key "=" Value
  84. Key ::= (KeywordChar | "_")+
  85. Value ::= ArgumentCharValue+
  86. ArgumentCharValue ::= any printing ASCII character except NL and SP.
  87. Terminator ::= "=====" or "===="
  88. Generators SHOULD use a 5-character terminator.
  89. Timestamp ::= Int
  90. Bandwidth ::= Int
  91. MasterKey ::= a base64-encoded Ed25519 public key, with
  92. padding characters omitted.
  93. DateTime ::= "YYYY-MM-DDTHH:MM:SS", as in ISO 8601
  94. CountryCode ::= Two capital ASCII letters ([A-Z]{2}), as defined in
  95. ISO 3166-1 alpha-2 plus "ZZ" to denote unknown country
  96. (eg the destination is in a Content Delivery Network).
  97. CountryCodeList ::= One or more CountryCode(s) separated by a comma
  98. ([A-Z]{2}(,[A-Z]{2})*).
  99. Note that key_value and value are defined in Tor directory protocol
  100. with different formats to KeyValue and Value here.
  101. Tor versions earlier than 0.3.5.1-alpha require all lines in the file
  102. to be 510 characters or less. The previous limit was 254 characters in
  103. Tor 0.2.6.2-alpha and earlier. Parsers MAY ignore longer Lines.
  104. Note that directory authorities are only supported on the two most
  105. recent stable Tor versions, so we expect that line limits will be
  106. removed after Tor 0.4.0 is released in 2019.
  107. 2.2. Header List format
  108. It consists of a Timestamp line and zero or more HeaderLines.
  109. All the header lines MUST conform to the HeaderLine format, except
  110. the first Timestamp line.
  111. The Timestamp line is not a HeaderLine to keep compatibility with
  112. the legacy Bandwidth File format.
  113. Some header Lines MUST appear in specific positions, as documented
  114. below. All other Lines can appear in any order.
  115. If a parser does not recognize any extra material in a header Line,
  116. the Line MUST be ignored.
  117. If a header Line does not conform to this format, the Line SHOULD be
  118. ignored by parsers.
  119. It consists of:
  120. Timestamp NL
  121. [At start, exactly once.]
  122. The Unix Epoch time in seconds of the most recent generator bandwidth
  123. result.
  124. If the generator implementation has multiple threads or
  125. subprocesses which can fail independently, it SHOULD take the most
  126. recent timestamp from each thread and use the oldest value. This
  127. ensures all the threads continue running.
  128. If there are threads that do not run continuously, they SHOULD be
  129. excluded from the timestamp calculation.
  130. If there are no recent results, the generator MUST NOT generate a new
  131. file.
  132. It does not follow the KeyValue format for backwards compatibility
  133. with version 1.0.0.
  134. "version=" version_number NL
  135. [In second position, zero or one time.]
  136. The specification document format version.
  137. It uses semantic versioning [5].
  138. This Line was added in version 1.1.0 of this specification.
  139. Version 1.0.0 documents do not contain this Line, and the
  140. version_number is considered to be "1.0.0".
  141. "software=" Value NL
  142. [Zero or one time.]
  143. The name of the software that created the document.
  144. This Line was added in version 1.1.0 of this specification.
  145. Version 1.0.0 documents do not contain this Line, and the software
  146. is considered to be "torflow".
  147. "software_version=" Value NL
  148. [Zero or one time.]
  149. The version of the software that created the document.
  150. The version may be a version_number, a git commit, or some other
  151. version scheme.
  152. This Line was added in version 1.1.0 of this specification.
  153. "file_created=" DateTime NL
  154. [Zero or one time.]
  155. The date and time timestamp in ISO 8601 format and UTC time zone
  156. when the file was created.
  157. This Line was added in version 1.1.0 of this specification.
  158. "generator_started=" DateTime NL
  159. [Zero or one time.]
  160. The date and time timestamp in ISO 8601 format and UTC time zone
  161. when the generator started.
  162. This Line was added in version 1.1.0 of this specification.
  163. "earliest_bandwidth=" DateTime NL
  164. [Zero or one time.]
  165. The date and time timestamp in ISO 8601 format and UTC time zone
  166. when the first relay bandwidth was obtained.
  167. This Line was added in version 1.1.0 of this specification.
  168. "latest_bandwidth=" DateTime NL
  169. [Zero or one time.]
  170. The date and time timestamp in ISO 8601 format and UTC time zone
  171. of the most recent generator bandwidth result.
  172. This time MUST be identical to the initial Timestamp line.
  173. This duplicate value is included to make the format easier for people
  174. to read.
  175. This Line was added in version 1.1.0 of this specification.
  176. "number_eligible_relays=" Int NL
  177. [Zero or one time.]
  178. The number of relays that have enough measurements to be
  179. included in the bandwidth file.
  180. This Line was added in version 1.2.0 of this specification.
  181. "minimum_percent_eligible_relays=" Int NL
  182. [Zero or one time.]
  183. The percentage of relays in the consensus that SHOULD be
  184. included in every generated bandwidth file.
  185. If this threshold is not reached, format versions 1.3.0 and earlier
  186. SHOULD NOT contain any relays. (Bandwidth files always include a
  187. header.)
  188. Format versions 1.4.0 and later SHOULD include all the relays for
  189. diagnostic purposes, even if this threshold is not reached. But these
  190. relays SHOULD be marked so that Tor does not vote on them.
  191. See section 1.4 for details.
  192. The minimum percentage is 60% in Torflow, so sbws uses
  193. 60% as the default.
  194. This Line was added in version 1.2.0 of this specification.
  195. "number_consensus_relays=" Int NL
  196. [Zero or one time.]
  197. The number of relays in the consensus.
  198. This Line was added in version 1.2.0 of this specification.
  199. "percent_eligible_relays=" Int NL
  200. [Zero or one time.]
  201. The number of eligible relays, as a percentage of the number
  202. of relays in the consensus.
  203. This line SHOULD be equal to:
  204. (number_eligible_relays * 100.0) / number_consensus_relays
  205. to the number of relays in the consensus to include in this file.
  206. This Line was added in version 1.2.0 of this specification.
  207. "minimum_number_eligible_relays=" Int NL
  208. [Zero or one time.]
  209. The minimum number of relays that SHOULD be included in the bandwidth
  210. file. See minimum_percent_eligible_relays for details.
  211. This line SHOULD be equal to:
  212. number_consensus_relays * (minimum_percent_eligible_relays / 100.0)
  213. This Line was added in version 1.2.0 of this specification.
  214. "scanner_country=" CountryCode NL
  215. [Zero or one time.]
  216. The country, as in political geolocation, where the generator is run.
  217. This Line was added in version 1.3.0 of this specification.
  218. "destinations_countries=" CountryCodeList NL
  219. [Zero or one time.]
  220. The country, as in political geolocation, or countries where the
  221. destination Web server(s) are located.
  222. The destination Web Servers serve the data that the generator retrieves
  223. to measure the bandwidth.
  224. This Line was added in version 1.3.0 of this specification.
  225. "recent_consensus_count=" Int NL
  226. [Zero or one time.].
  227. The number of the different consensuses seen in the last data_period
  228. days. (data_period is 5 by default.)
  229. Assuming that Tor clients fetch a consensus every 1-2 hours,
  230. and that the data_period is 5 days, the Value of this Key SHOULD be
  231. between:
  232. data_period * 24 / 2 = 60
  233. data_period * 24 = 120
  234. This Line was added in version 1.4.0 of this specification.
  235. "recent_priority_list_count=" Int NL
  236. [Zero or one time.]
  237. The number of times that a list with a subset of relays prioritized
  238. to be measured has been created in the last data_period days.
  239. (data_period is 5 by default.)
  240. In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
  241. approximately:
  242. data_period * 24 / 1.5 = 80
  243. Being 1.5 the approximate number of hours it takes to measure a
  244. priority list of 7000 * 0.05 (350) relays, when the fraction of relays
  245. in a priority list is the 5% (0.05).
  246. This Line was added in version 1.4.0 of this specification.
  247. "recent_priority_relay_count=" Int NL
  248. [Zero or one time.]
  249. The number of relays that has been in in the list of relays prioritized
  250. to be measured in the last data_period days. (data_period is 5 by
  251. default.)
  252. In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
  253. approximately:
  254. 80 * (7000 * 0.05) = 28000
  255. Being 0.05 (5%) the fraction of relays in a priority list and 80
  256. the approximate number of priority lists (see
  257. "recent_priority_list_count").
  258. This Line was added in version 1.4.0 of this specification.
  259. "recent_measurement_attempt_count=" Int NL
  260. [Zero or one time.]
  261. The number of times that any relay has been queued to be measured
  262. in the last data_period days. (data_period is 5 by default.)
  263. In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
  264. approximately the same as "recent_priority_relay_count",
  265. assuming that there is one attempt to measure a relay for each relay that
  266. has been prioritized unless there are system, network or implementation
  267. issues.
  268. This Line was added in version 1.4.0 of this specification.
  269. "recent_measurement_failure_count=" Int NL
  270. [Zero or one time.]
  271. The number of times that the scanner attempted to measure a relay in
  272. the last data_period days (5 by default), but the relay has not been
  273. measured because of system, network or implementation issues.
  274. This Line was added in version 1.4.0 of this specification.
  275. "recent_measurements_excluded_error_count=" Int NL
  276. [Zero or one time.]
  277. The number of relays that have no successful measurements in the last
  278. data_period days (5 by default).
  279. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  280. This Line was added in version 1.4.0 of this specification.
  281. "recent_measurements_excluded_near_count=" Int NL
  282. [Zero or one time.]
  283. The number of relays that have some successful measurements in the last
  284. data_period days (5 by default), but all those measurements were
  285. performed in a period of time that was too short (by default 1 day).
  286. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  287. This Line was added in version 1.4.0 of this specification.
  288. "recent_measurements_excluded_old_count=" Int NL
  289. [Zero or one time.]
  290. The number of relays that have some successful measurements, but all
  291. those measurements are too old (more than 5 days, by default).
  292. Excludes relays that are already counted in
  293. recent_measurements_excluded_near_count.
  294. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  295. This Line was added in version 1.4.0 of this specification.
  296. "recent_measurements_excluded_few_count=" Int NL
  297. [Zero or one time.]
  298. The number of relays that don't have enough recent successful
  299. measurements. (Fewer than 2 measurements in the last 5 days, by
  300. default).
  301. Excludes relays that are already counted in
  302. recent_measurements_excluded_near_count and
  303. recent_measurements_excluded_old_count.
  304. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  305. This Line was added in version 1.4.0 of this specification.
  306. "time_to_report_half_network=" Int NL
  307. [Zero or one time.]
  308. The time in seconds that it would take to report measurements about the
  309. half of the network, given the number of eligible relays and the time
  310. it took in the last days (5 days, by default).
  311. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  312. This Line was added in version 1.4.0 of this specification.
  313. KeyValue NL
  314. [Zero or more times.]
  315. There MUST NOT be multiple KeyValue header Lines with the same key.
  316. If there are, the parser SHOULD choose an arbitrary Line.
  317. If a parser does not recognize a Keyword in a KeyValue Line, it
  318. MUST be ignored.
  319. Future format versions may include additional KeyValue header Lines.
  320. Additional header Lines will be accompanied by a minor version
  321. increment.
  322. Implementations MAY add additional header Lines as needed. This
  323. specification SHOULD be updated to avoid conflicting meanings for
  324. the same header keys.
  325. Parsers MUST NOT rely on the order of these additional Lines.
  326. Additional header Lines MUST NOT use any keywords specified in the
  327. relay measurements format.
  328. If there are, the parser MAY ignore conflicting keywords.
  329. Terminator NL
  330. [Zero or one time.]
  331. The Header List section ends with a Terminator.
  332. In version 1.0.0, Header List ends when the first relay bandwidth
  333. is found conforming to the next section.
  334. Implementations of version 1.1.0 and later SHOULD use a 5-character
  335. terminator.
  336. Tor 0.4.0.1-alpha and later look for a 5-character terminator,
  337. or the first relay bandwidth line. sbws versions 0.1.0 to 1.0.2
  338. used a 4-character terminator, this bug was fixed in 1.0.3.
  339. 2.3. Relay Line format
  340. It consists of zero or more RelayLines containing relay ids and
  341. bandwidths. The relays and their KeyValues are in arbitrary order.
  342. There MUST NOT be multiple KeyValue pairs with the same key in the same
  343. RelayLine. If there are, the parser SHOULD choose an arbitrary Value.
  344. There MUST NOT be multiple RelayLines per relay identity (node_id or
  345. master_key_ed25519). If there are, parsers SHOULD issue a warning.
  346. Parers MAY reject the file, choose an arbitrary RelayLine, or ignore
  347. both RelayLines.
  348. If a parser does not recognize any extra material in a RelayLine,
  349. the extra material MUST be ignored.
  350. Each RelayLine includes the following KeyValue pairs:
  351. "node_id=" hexdigest
  352. [Exactly once.]
  353. The fingerprint for the relay's RSA identity key.
  354. Note: In bandwidth files read by Tor versions earlier than
  355. 0.3.4.1-alpha, node_id MUST NOT be at the end of the Line.
  356. These authority versions are no longer supported.
  357. Current Tor versions ignore master_key_ed25519, so node_id MUST be
  358. present in each relay Line.
  359. Implementations of version 1.1.0 and later SHOULD include both node_id
  360. and master_key_ed25519. Parsers SHOULD accept Lines that contain at
  361. least one of them.
  362. "master_key_ed25519=" MasterKey
  363. [Zero or one time.]
  364. The relays's master Ed25519 key, base64 encoded,
  365. without trailing "="s, to avoid ambiguity with KeyValue "="
  366. character.
  367. This KeyValue pair SHOULD be present, see the note under node_id.
  368. This KeyValue was added in version 1.1.0 of this specification.
  369. "bw=" Bandwidth
  370. [Exactly once.]
  371. The bandwidth of this relay in kilobytes per second.
  372. No Zero Bandwidths:
  373. Tor accepts zero bandwidths, but they trigger bugs in older Tor
  374. implementations. Therefore, implementations SHOULD NOT produce zero
  375. bandwidths. Instead, they SHOULD use one as their minimum bandwidth.
  376. If there are zero bandwidths, the parser MAY ignore them.
  377. Bandwidth Aggregation:
  378. Multiple measurements can be aggregated using an averaging scheme,
  379. such as a mean, median, or decaying average.
  380. Bandwidth Scaling:
  381. Torflow scales bandwidths to kilobytes per second. Other
  382. implementations SHOULD use kilobytes per second for their initial
  383. bandwidth scaling.
  384. If different implementations or configurations are used in votes for
  385. the same network, their measurements MAY need further scaling. See
  386. Appendix B for information about scaling, and one possible scaling
  387. method.
  388. MaxAdvertisedBandwidth:
  389. Bandwidth generators MUST limit the relays' measured bandwidth based
  390. on the MaxAdvertisedBadwidth.
  391. A relay's MaxAdvertisedBandwidth limits the bandwidth-avg in its
  392. descriptor. bandwidth-avg is the minimum of MaxAdvertisedBandwidth,
  393. BandwidthRate, RelayBandwidthRate, BandwidthBurst, and
  394. RelayBandwidthBurst.
  395. Therefore, generators MUST limit a relay's measured bandwidth to its
  396. descriptor's bandwidth-avg. This limit needs to be implemented in the
  397. generator, because generators may scale consensus weights before
  398. sending them to Tor.
  399. Generators SHOULD NOT limit measured bandwidths based on descriptors'
  400. bandwidth-observed, because that penalises new relays.
  401. sbws limits the relay's measured bandwidth to the bandwidth-avg
  402. advertised.
  403. Torflow partitions relays based on their bandwidth. For unmeasured
  404. relays, Torflow uses the minimum of all descriptor bandwidths,
  405. including bandwidth-avg (MaxAdvertisedBandwidth) and
  406. bandwidth-observed. Then Torflow measures the relays in each partition
  407. against each other, which implicitly limits a relay's measured
  408. bandwidth to the bandwidths of similar relays.
  409. Torflow also generates consensus weights based on the ratio between the
  410. measured bandwidth and the minimum of all descriptor bandwidths (at the
  411. time of the measurement). So when an operator reduces the
  412. MaxAdvertisedBandwidth for a relay, Torflow reduces that relay's
  413. measured bandwidth.
  414. KeyValue
  415. [Zero or more times.]
  416. Future format versions may include additional KeyValue pairs on a
  417. RelayLine.
  418. Additional KeyValue pairs will be accompanied by a minor version
  419. increment.
  420. Implementations MAY add additional relay KeyValue pairs as needed.
  421. This specification SHOULD be updated to avoid conflicting meanings
  422. for the same Keywords.
  423. Parsers MUST NOT rely on the order of these additional KeyValue
  424. pairs.
  425. Additional KeyValue pairs MUST NOT use any keywords specified in the
  426. header format.
  427. If there are, the parser MAY ignore conflicting keywords.
  428. 2.4. Implementation details
  429. 2.4.1 Writing bandwidth files atomically
  430. To avoid inconsistent reads, implementations SHOULD write bandwidth files
  431. atomically. If the file is transferred from another host, it SHOULD be
  432. written to a temporary path, then renamed to the V3BandwidthsFile path.
  433. sbws versions 0.7.0 and later write the bandwidth file to an archival
  434. location, create a temporary symlink to that location, then atomically rename
  435. the symlink
  436. to the configured V3BandwidthsFile path.
  437. Torflow does not write bandwidth files atomically.
  438. 2.4.2. Additional KeyValue pair definitions
  439. KeyValue pairs in RelayLines that current implementations generate.
  440. 2.4.2.1. Simple Bandwidth Scanner
  441. sbws RelayLines contain these keys:
  442. "node_id=" hexdigest
  443. As above.
  444. "bw=" Bandwidth
  445. As above.
  446. "nick=" nickname
  447. [Exactly once.]
  448. The relay nickname.
  449. Torflow also has a "nick=" KeyValue.
  450. "rtt=" Int
  451. [Zero or one time.]
  452. The Round Trip Time in milliseconds to obtain 1 byte of data.
  453. This KeyValue was added in version 1.1.0 of this specification.
  454. It became optional in version 1.3.0 or 1.4.0 of this specification.
  455. "time=" DateTime
  456. [Exactly once.]
  457. The date and time timestamp in ISO 8601 format and UTC time zone
  458. when the last bandwidth was obtained.
  459. This KeyValue was added in version 1.1.0 of this specification.
  460. The Torflow equivalent is "measured_at=".
  461. "success=" Int
  462. [Zero or one time.]
  463. The number of times that the bandwidth measurements for this relay were
  464. successful.
  465. This KeyValue was added in version 1.1.0 of this specification.
  466. "error_circ=" Int
  467. [Zero or one time.]
  468. The number of times that the bandwidth measurements for this relay
  469. failed because of circuit failures.
  470. This KeyValue was added in version 1.1.0 of this specification.
  471. The Torflow equivalent is "circ_fail=".
  472. "error_stream=" Int
  473. [Zero or one time.]
  474. The number of times that the bandwidth measurements for this relay
  475. failed because of stream failures.
  476. This KeyValue was added in version 1.1.0 of this specification.
  477. "error_destination=" Int
  478. [Zero or one time.]
  479. The number of times that the bandwidth measurements for this relay
  480. failed because the destination Web server was not available.
  481. This KeyValue was added in version 1.4.0 of this specification.
  482. "error_second_relay=" Int
  483. [Zero or one time.]
  484. The number of times that the bandwidth measurements for this relay
  485. failed because sbws could not find a second relay for the test circuit.
  486. This KeyValue was added in version 1.4.0 of this specification.
  487. "error_misc=" Int
  488. [Zero or one time.]
  489. The number of times that the bandwidth measurements for this relay
  490. failed because of other reasons.
  491. This KeyValue was added in version 1.1.0 of this specification.
  492. "bw_mean=" Int
  493. [Zero or one time.]
  494. The measured bandwidth mean for this relay in bytes per second.
  495. This KeyValue was added in version 1.2.0 of this specification.
  496. "bw_median=" Int
  497. [Zero or one time.]
  498. The measured bandwidth median for this relay in bytes per second.
  499. This KeyValue was added in version 1.2.0 of this specification.
  500. "desc_bw_average=" Int
  501. [Zero or one time.]
  502. The descriptor average bandwidth for this relay in bytes per second.
  503. This KeyValue was added in version 1.2.0 of this specification.
  504. "desc_obs_bw_last=" Int
  505. [Zero or one time.]
  506. The last descriptor observed bandwidth for this relay in bytes per
  507. second.
  508. This KeyValue was added in version 1.2.0 of this specification.
  509. "desc_obs_bw_mean=" Int
  510. [Zero or one time.]
  511. The descriptor observed bandwidth mean for this relay in bytes per
  512. second.
  513. This KeyValue was added in version 1.2.0 of this specification.
  514. "relay_recent_measurements_excluded_error_count=" Int
  515. [Zero or one time.]
  516. The number of recent relay measurement attempts that failed.
  517. Measurements are recent if they are in the last data_period days
  518. (5 by default).
  519. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  520. This KeyValue was added in version 1.4.0 of this specification.
  521. "relay_recent_measurements_excluded_near_count=" Int
  522. [Zero or one time.]
  523. When all of a relay's recent successful measurements were performed in
  524. a period of time that was too short (by default 1 day), the relay is
  525. excluded. This KeyValue contains the number of recent successful
  526. measurements for the relay that were ignored for this reason.
  527. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  528. This KeyValue was added in version 1.4.0 of this specification.
  529. "relay_recent_measurements_excluded_old_count=" Int
  530. [Zero or one time.]
  531. The number of successful measurements for this relay that are too old
  532. (more than data_period days, 5 by default).
  533. Excludes measurements that are already counted in
  534. relay_recent_measurements_excluded_near_count.
  535. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  536. This KeyValue was added in version 1.4.0 of this specification.
  537. "recent_measurements_excluded_few_count=" Int
  538. [Zero or one time.]
  539. The number of successful measurements for this relay that were ignored
  540. because the relay did not have enough successful measurements (fewer
  541. than 2, by default).
  542. Excludes measurements that are already counted in
  543. relay_recent_measurements_excluded_near_count or
  544. relay_recent_measurements_excluded_old_count.
  545. (See the note in section 1.4, version 1.4.0, about excluded relays.)
  546. This KeyValue was added in version 1.4.0 of this specification.
  547. "under_min_report=" bool
  548. [Zero or one time.]
  549. If the value is 1, there are not enough eligible relays in the
  550. bandwidth file, and Tor bandwidth authorities MAY NOT vote on this
  551. relay. (Current Tor versions do not change their behaviour based on
  552. the "under_min_report" key.)
  553. If the value is 0 or the KeyValue is not present, there are enough
  554. relays in the bandwidth file.
  555. Because Tor versions released before April 2019 (see section 1.4. for
  556. the full list of versions) ignore "vote=0", generator implementations
  557. MUST NOT change the bandwidths for under_min_report relays. Using the
  558. same bw value makes authorities that do not understand "vote=0"
  559. or "under_min_report=1" produce votes that don't change relay weights
  560. too much. It also avoids flapping when the reporting threshold is
  561. reached.
  562. This KeyValue was added in version 1.4.0 of this specification.
  563. "unmeasured=" bool
  564. [Zero or one time.]
  565. If the value is 1, this relay was not successfully measured and
  566. Tor bandwidth authorities MAY NOT vote on this relay.
  567. (Current Tor versions do not change their behaviour based on
  568. the "unmeasured" key.)
  569. If the value is 0 or the KeyValue is not present, this relay
  570. was successfully measured.
  571. Because Tor versions released before April 2019 (see section 1.4. for
  572. the full list of versions) ignore "vote=0", generator implementations
  573. MUST set "bw=1" for unmeasured relays. Using the minimum bw value
  574. makes authorities that do not understand "vote=0" or "unmeasured=1"
  575. produce votes that don't change relay weights too much.
  576. This KeyValue was added in version 1.4.0 of this specification.
  577. "vote=" bool
  578. [Zero or one time.]
  579. If the value is 0, Tor directory authorities SHOULD ignore the relay's
  580. entry in the bandwidth file. They SHOULD vote for the relay the same
  581. way they would vote for a relay that is not present in the file.
  582. This MAY be the case when this relay was not successfully measured but
  583. it is included in the Bandwidth File, to diagnose why they were not
  584. measured.
  585. If the value is 1 or the KeyValue is not present, Tor directory
  586. authorities MUST use the relay's bw value in any votes for that relay.
  587. Implementations MUST also set "bw=1" for unmeasured relays.
  588. But they MUST NOT change the bw for under_min_report relays.
  589. (See the explanations under "unmeasured" and "under_min_report"
  590. for more details.)
  591. This KeyValue was added in version 1.4.0 of this specification.
  592. 2.4.2.2. Torflow
  593. Torflow RelayLines include node_id and bw, and other KeyValue pairs [2].
  594. References:
  595. 1. https://gitweb.torproject.org/torflow.git
  596. 2. https://gitweb.torproject.org/torflow.git/tree/NetworkScanners/BwAuthority/README.spec.txt#n332
  597. The Torflow specification is outdated, and does not match the current
  598. implementation. See section A.1. for the format produced by Torflow.
  599. 3. https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt
  600. 4. https://gitweb.torproject.org/torspec.git/tree/version-spec.txt
  601. 5. https://semver.org/
  602. A. Sample data
  603. The following has not been obtained from any real measurement.
  604. A.1. Generated by Torflow
  605. This an example version 1.0.0 document:
  606. 1523911758
  607. node_id=$68A483E05A2ABDCA6DA5A3EF8DB5177638A27F80 bw=760 nick=Test measured_at=1523911725 updated_at=1523911725 pid_error=4.11374090719 pid_error_sum=4.11374090719 pid_bw=57136645 pid_delta=2.12168374577 circ_fail=0.2 scanner=/filepath
  608. node_id=$96C15995F30895689291F455587BD94CA427B6FC bw=189 nick=Test2 measured_at=1523911623 updated_at=1523911623 pid_error=3.96703337994 pid_error_sum=3.96703337994 pid_bw=47422125 pid_delta=2.65469736988 circ_fail=0.0 scanner=/filepath
  609. A.2. Generated by sbws version 0.1.0
  610. 1523911758
  611. version=1.1.0
  612. software=sbws
  613. software_version=0.1.0
  614. latest_bandwidth=2018-04-16T20:49:18
  615. file_created=2018-04-16T21:49:18
  616. generator_started=2018-04-16T15:13:25
  617. earliest_bandwidth=2018-04-16T15:13:26
  618. ====
  619. 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
  620. 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
  621. A.3. Generated by sbws version 1.0.3
  622. 1523911758
  623. version=1.2.0
  624. latest_bandwidth=2018-04-16T20:49:18
  625. file_created=2018-04-16T21:49:18
  626. generator_started=2018-04-16T15:13:25
  627. earliest_bandwidth=2018-04-16T15:13:26
  628. minimum_number_eligible_relays=3862
  629. minimum_percent_eligible_relays=60
  630. number_consensus_relays=6436
  631. number_eligible_relays=6000
  632. percent_eligible_relays=93
  633. software=sbws
  634. software_version=1.0.3
  635. =====
  636. 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
  637. 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
  638. A.3.1. When there are not enough eligible measured relays:
  639. 1540496079
  640. version=1.2.0
  641. earliest_bandwidth=2018-10-20T19:35:52
  642. file_created=2018-10-25T19:35:03
  643. generator_started=2018-10-25T11:42:56
  644. latest_bandwidth=2018-10-25T19:34:39
  645. minimum_number_eligible_relays=3862
  646. minimum_percent_eligible_relays=60
  647. number_consensus_relays=6436
  648. number_eligible_relays=2960
  649. percent_eligible_relays=46
  650. software=sbws
  651. software_version=1.0.3
  652. =====
  653. A.4. Headers generated by sbws version 1.0.4
  654. 1523911758
  655. version=1.3.0
  656. latest_bandwidth=2018-04-16T20:49:18
  657. destinations_countries=TH,ZZ
  658. file_created=2018-04-16T21:49:18
  659. generator_started=2018-04-16T15:13:25
  660. earliest_bandwidth=2018-04-16T15:13:26
  661. minimum_number_eligible_relays=3862
  662. minimum_percent_eligible_relays=60
  663. number_consensus_relays=6436
  664. number_eligible_relays=6000
  665. percent_eligible_relays=93
  666. scanner_country=SN
  667. software=sbws
  668. software_version=1.0.4
  669. =====
  670. A.5 Generated by sbws version 1.1.0
  671. 1523911758
  672. version=1.4.0
  673. latest_bandwidth=2018-04-16T20:49:18
  674. destinations_countries=TH,ZZ
  675. file_created=2018-04-16T21:49:18
  676. generator_started=2018-04-16T15:13:25
  677. earliest_bandwidth=2018-04-16T15:13:26
  678. minimum_number_eligible_relays=3862
  679. minimum_percent_eligible_relays=60
  680. number_consensus_relays=6436
  681. number_eligible_relays=6000
  682. percent_eligible_relays=93
  683. recent_measurement_attempt_count=6243
  684. recent_measurement_failure_count=732
  685. recent_measurements_excluded_error_count=969
  686. recent_measurements_excluded_few_count=3946
  687. recent_measurements_excluded_near_count=90
  688. recent_measurements_excluded_old_count=0
  689. recent_priority_list_count=20
  690. recent_priority_relay_count=6243
  691. scanner_country=SN
  692. software=sbws
  693. software_version=1.1.0
  694. time_to_report_half_network=57273
  695. =====
  696. bw=1 error_circ=1 error_destination=0 error_misc=0 error_second_relay=0 error_stream=0 master_key_ed25519=J3HQ24kOQWac3L1xlFLp7gY91qkb5NuKxjj1BhDi+m8 nick=snap269 node_id=$DC4D609F95A52614D1E69C752168AF1FCAE0B05F relay_recent_measurement_attempt_count=3 relay_recent_measurements_excluded_error_count=1 relay_recent_measurements_excluded_near_count=3 relay_recent_consensus_count=3 relay_recent_priority_list_count=3 success=3 time=2019-03-16T18:20:57 unmeasured=1 vote=0
  697. bw=1 error_circ=0 error_destination=0 error_misc=0 error_second_relay=0 error_stream=2 master_key_ed25519=h6ZB1E1yBFWIMloUm9IWwjgaPXEpL5cUbuoQDgdSDKg nick=relay node_id=$C4544F9E209A9A9B99591D548B3E2822236C0503 relay_recent_measurement_attempt_count=3 relay_recent_measurements_excluded_error_count=2 relay_recent_measurements_excluded_few_count=1 relay_recent_consensus_count=3 relay_recent_priority_list_count=3 success=1 time=2019-03-17T06:50:58 unmeasured=1 vote=0
  698. B. Scaling bandwidths
  699. B.1. Scaling requirements
  700. Tor accepts zero bandwidths, but they trigger bugs in older Tor
  701. implementations. Therefore, scaling methods SHOULD perform the
  702. following checks:
  703. * If the total bandwidth is zero, all relays should be given equal
  704. bandwidths.
  705. * If the scaled bandwidth is zero, it should be rounded up to one.
  706. Initial experiments indicate that scaling may not be needed for
  707. torflow and sbws, because their measured bandwidths are similar
  708. enough already.
  709. B.2. A linear scaling method
  710. If scaling is required, here is a simple linear bandwith scaling
  711. method, which ensures that all bandwidth votes contain approximately
  712. the same total bandwidth:
  713. 1. Calculate the relay quota by dividing the total measured bandwidth
  714. in all votes, by the number of relays with measured bandwidth
  715. votes. In the public tor network, this is approximately 7500 as of
  716. April 2018. The quota should be a consensus parameter, so it can be
  717. adjusted for all generators on the network.
  718. 2. Calculate a vote quota by multiplying the relay quota by the number
  719. of relays this bandwidth authority has measured
  720. bandwidths for.
  721. 3. Calculate a scaling factor by dividing the vote quota by the
  722. total unscaled measured bandwidth in this bandwidth
  723. authority's upcoming vote.
  724. 4. Multiply each unscaled measured bandwidth by the scaling
  725. factor.
  726. Now, the total scaled bandwidth in the upcoming vote is
  727. approximately equal to the quota.
  728. B.3. Quota changes
  729. If all generators are using scaling, the quota can be gradually
  730. reduced or increased as needed. Smaller quotas decrease the size
  731. of uncompressed consensuses, and may decrease the size of
  732. consensus diffs and compressed consensuses. But if the relay
  733. quota is too small, some relays may be over- or under-weighted.
  734. B.4. Torflow aggreation
  735. Torflow implements two methods to compute the bandwidth values from the
  736. (stream) bandwidth measurements: with and without PID control feedback.
  737. The method described here is without PID control (see Torflow
  738. specification, section 2.2).
  739. In the following sections, the relays' measured bandwidth refer to the
  740. ones that this bandwidth authority has measured for the relays that
  741. would be included in the next bandwidth authority's upcoming vote.
  742. 1. Calculate the filtered bandwidth for each relay:
  743. - choose the relay's measurements (`bw_j`) that are equal or greater
  744. than the mean of the measurements for this relay
  745. - calculate the mean of those measurements
  746. In pseudocode:
  747. bw_filt_i = mean(max(mean(bw_j), bw_j))
  748. 2. Calculate network averages:
  749. - calculate the filtered average by dividing the sum of all the
  750. relays' filtered bandwidth by the number of relays that have been
  751. measured (`n`), ie, calculate the mean average of the relays'
  752. filtered bandwidth.
  753. - calculate the stream average by dividing the sum of all the
  754. relays' filtered bandwidth by the number of relays that have been
  755. measured (`n`), ie, calculate the mean average or the relays'
  756. measured bandwidth.
  757. In pseudocode:
  758. bw_avg_filt_ = bw_filt_i / n
  759. bw_avg_strm = bw_i / n
  760. 3. Calculate ratios for each relay:
  761. - calculate the filtered ratio by dividing each relay filtered
  762. bandwidth by the filtered average
  763. - calculate the stream ratio by dividing each relay measured
  764. bandwidth by the stream average
  765. In pseudocode:
  766. r_filt_i = bw_filt_i / bw_avg_filt
  767. r_strm_i = bw_i / bw_avg_strm
  768. 4. Calculate the final ratio for each relay:
  769. The final ratio is the larger between the filtered bandwidth and the
  770. stream bandwidth.
  771. In pseudocode:
  772. r_i = max(r_filt_i, r_strm_i)
  773. 5. Calculate the scaled bandwidth for each relay:
  774. The most recent descriptor observed bandwidth (`bw_obs_i`) is
  775. multiplied by the ratio
  776. In pseudocode:
  777. bw_new_i = r_i * bw_obs_i
  778. <<In this way, the resulting network status consensus bandwidth
  779. values are effectively re-weighted proportional to how much faster
  780. the node was as compared to the rest of the network.>>