commit cbb2c760b3cd34d3c421658baddaccdfc6ea5c38 Author: teor teor@torproject.org Date: Mon Jan 14 11:38:47 2019 +1000
bandwidth: use consistent 2 space indents, and reflow long lines --- bandwidth-file-spec.txt | 664 ++++++++++++++++++++++++------------------------ 1 file changed, 333 insertions(+), 331 deletions(-)
diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt index 48de171..965191d 100644 --- a/bandwidth-file-spec.txt +++ b/bandwidth-file-spec.txt @@ -116,425 +116,427 @@
2.2. Header List format
-Some header Lines MUST appear in specific positions, as documented -below. All other Lines can appear in any order. + Some header Lines MUST appear in specific positions, as documented + below. All other Lines can appear in any order.
-If a parser does not recognize any extra material in a header Line, -the Line MUST be ignored. + If a parser does not recognize any extra material in a header Line, + the Line MUST be ignored.
-If a header Line does not conform to this format, the Line SHOULD be -ignored by parsers. + If a header Line does not conform to this format, the Line SHOULD be + ignored by parsers.
-It consists of: + It consists of:
- Timestamp NL + Timestamp NL
- [At start, exactly once.] + [At start, exactly once.]
- The Unix Epoch time in seconds of the most recent generator bandwidth - result. + The Unix Epoch time in seconds of the most recent generator bandwidth + result.
- If the generator implementation has multiple threads or - subprocesses which can fail independently, it SHOULD take the most - recent timestamp from each thread and use the oldest value. This - ensures all the threads continue running. + If the generator implementation has multiple threads or + subprocesses which can fail independently, it SHOULD take the most + recent timestamp from each thread and use the oldest value. This + ensures all the threads continue running.
- If there are threads that do not run continuously, they SHOULD be - excluded from the timestamp calculation. + If there are threads that do not run continuously, they SHOULD be + excluded from the timestamp calculation.
- If there are no recent results, the generator MUST NOT generate a new file. + If there are no recent results, the generator MUST NOT generate a new + file.
- It does not follow the KeyValue format for backwards compatibility - with version 1.0.0. + It does not follow the KeyValue format for backwards compatibility + with version 1.0.0.
- "version=" version_number NL + "version=" version_number NL
- [In second position, zero or one time.] + [In second position, zero or one time.]
- The specification document format version. - It uses semantic versioning [5]. + The specification document format version. + It uses semantic versioning [5].
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- Version 1.0.0 documents do not contain this Line, and the - version_number is considered to be "1.0.0". + Version 1.0.0 documents do not contain this Line, and the + version_number is considered to be "1.0.0".
- "software=" Value NL + "software=" Value NL
- [Zero or one time.] + [Zero or one time.]
- The name of the software that created the document. + The name of the software that created the document.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- Version 1.0.0 documents do not contain this Line, and the software - is considered to be "torflow". + Version 1.0.0 documents do not contain this Line, and the software + is considered to be "torflow".
- "software_version=" Value NL + "software_version=" Value NL
- [Zero or one time.] + [Zero or one time.]
- The version of the software that created the document. - The version may be a version_number, a git commit, or some other - version scheme. + The version of the software that created the document. + The version may be a version_number, a git commit, or some other + version scheme.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- "file_created=" DateTime NL + "file_created=" DateTime NL
- [Zero or one time.] + [Zero or one time.]
- The date and time timestamp in ISO 8601 format and UTC time zone - when the file was created. + The date and time timestamp in ISO 8601 format and UTC time zone + when the file was created.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- "generator_started=" DateTime NL + "generator_started=" DateTime NL
- [Zero or one time.] + [Zero or one time.]
- The date and time timestamp in ISO 8601 format and UTC time zone - when the generator started. + The date and time timestamp in ISO 8601 format and UTC time zone + when the generator started.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- "earliest_bandwidth=" DateTime NL + "earliest_bandwidth=" DateTime NL
- [Zero or one time.] + [Zero or one time.]
- The date and time timestamp in ISO 8601 format and UTC time zone - when the first relay bandwidth was obtained. + The date and time timestamp in ISO 8601 format and UTC time zone + when the first relay bandwidth was obtained.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- "latest_bandwidth=" DateTime NL + "latest_bandwidth=" DateTime NL
- [Zero or one time.] + [Zero or one time.]
- The date and time timestamp in ISO 8601 format and UTC time zone - of the most recent generator bandwidth result. + The date and time timestamp in ISO 8601 format and UTC time zone + of the most recent generator bandwidth result.
- This time MUST be identical to the initial Timestamp line. + This time MUST be identical to the initial Timestamp line.
- This duplicate value is included to make the format easier for people - to read. + This duplicate value is included to make the format easier for people + to read.
- This Line was added in version 1.1.0 of this specification. + This Line was added in version 1.1.0 of this specification.
- "number_eligible_relays=" Int NL + "number_eligible_relays=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of relays that have enough measurements to be - included in the bandwidth file. + The number of relays that have enough measurements to be + included in the bandwidth file.
- This Line was added in version 1.2.0 of this specification. + This Line was added in version 1.2.0 of this specification.
- "minimum_percent_eligible_relays=" Int NL + "minimum_percent_eligible_relays=" Int NL
- [Zero or one time.] + [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. + 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.
- The minimum percentage is 60% in Torflow, so sbws uses - 60% as the default. + The minimum percentage is 60% in Torflow, so sbws uses + 60% as the default.
- This Line was added in version 1.2.0 of this specification. + This Line was added in version 1.2.0 of this specification.
- "number_consensus_relays=" Int NL + "number_consensus_relays=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of relays in the consensus. + The number of relays in the consensus.
- This Line was added in version 1.2.0 of this specification. + This Line was added in version 1.2.0 of this specification.
- "percent_eligible_relays=" Int NL + "percent_eligible_relays=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of eligible relays, as a percentage of the number - of relays in the consensus. + The number of eligible relays, as a percentage of the number + of relays in the consensus.
- This line SHOULD be equal to: - (number_eligible_relays * 100.0) / number_consensus_relays - to the number of relays in the consensus to include in this file. + This line SHOULD be equal to: + (number_eligible_relays * 100.0) / number_consensus_relays + to the number of relays in the consensus to include in this file.
- This Line was added in version 1.2.0 of this specification. + This Line was added in version 1.2.0 of this specification.
- "minimum_number_eligible_relays=" Int NL + "minimum_number_eligible_relays=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The minimum number of relays to include in the bandwidth file. + The minimum number of relays to include in the bandwidth file.
- This line SHOULD be equal to: - number_consensus_relays * (minimum_percent_eligible_relays / 100.0) + This line SHOULD be equal to: + number_consensus_relays * (minimum_percent_eligible_relays / 100.0)
- This Line was added in version 1.2.0 of this specification. + This Line was added in version 1.2.0 of this specification.
- KeyValue NL + KeyValue NL
- [Zero or more times.] + [Zero or more times.]
- There MUST NOT be multiple KeyValue header Lines with the same key. - If there are, the parser SHOULD choose an arbitrary Line. + There MUST NOT be multiple KeyValue header Lines with the same key. + If there are, the parser SHOULD choose an arbitrary Line.
- If a parser does not recognize a Keyword in a KeyValue Line, it - MUST be ignored. + If a parser does not recognize a Keyword in a KeyValue Line, it + MUST be ignored.
- Future format versions may include additional KeyValue header Lines. - Additional header Lines will be accompanied by a minor version - increment. + Future format versions may include additional KeyValue header Lines. + Additional header Lines will be accompanied by a minor version + increment.
- Implementations MAY add additional header Lines as needed. This - specification SHOULD be updated to avoid conflicting meanings for - the same header keys. + Implementations MAY add additional header Lines as needed. This + specification SHOULD be updated to avoid conflicting meanings for + the same header keys.
- Parsers MUST NOT rely on the order of these additional Lines. + Parsers MUST NOT rely on the order of these additional Lines.
- Additional header Lines MUST NOT use any keywords specified in the - relay measurements format. - If there are, the parser MAY ignore conflicting keywords. + Additional header Lines MUST NOT use any keywords specified in the + relay measurements format. + If there are, the parser MAY ignore conflicting keywords.
- Terminator NL + Terminator NL
- [Zero or one time.] + [Zero or one time.]
- The Header List section ends with this Terminator. + The Header List section ends with this Terminator.
- 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 and later SHOULD include this Line. + 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 and later SHOULD include this Line.
2.3. Relay Line format
-It consists of zero or more RelayLines with the relays' bandwidth -in arbitrary order. + It consists of zero or more RelayLines with the relays' bandwidth + in arbitrary order.
-There MUST NOT be multiple KeyValue pairs with the same key in the same -RelayLine. If there are, the parser SHOULD choose an arbitrary Value. + There MUST NOT be multiple KeyValue pairs with the same key in the same + RelayLine. If there are, the parser SHOULD choose an arbitrary Value.
-There MUST NOT be multiple RelayLine per relay identity (node_id or -master_key_ed25519). If there are, parsers SHOULD issue a warning. -Parers MAY choose an arbitrary value, or ignore both values. + There MUST NOT be multiple RelayLine per relay identity (node_id or + master_key_ed25519). If there are, parsers SHOULD issue a warning. + Parers MAY choose an arbitrary value, or ignore both values.
-If a parser does not recognize any extra material in a RelayLine, -the extra material MUST be ignored. + 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: + Each RelayLine MUST include the following KeyValue pairs:
- "node_id=" hexdigest + "node_id=" hexdigest
- [Exactly once.] + [Exactly once.]
- The fingerprint for the relay's RSA identity key. + 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. + 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 + "master_key_ed25519=" MasterKey
- [Zero or one time.] + [Zero or one time.]
- The relays's master Ed25519 key, base64 encoded, - without trailing "="s, to avoid ambiguity with KeyValue "=" - character. + The relays's master Ed25519 key, base64 encoded, + without trailing "="s, to avoid ambiguity with KeyValue "=" + character.
- Implementations of version 1.1.0 SHOULD include both node_id and - master_key_ed25519. - Parsers SHOULD accept Lines that contain at least one of them. + Implementations of version 1.1.0 SHOULD include both node_id and + master_key_ed25519. + Parsers SHOULD accept Lines that contain at least one of them.
- "bw=" Bandwidth + "bw=" Bandwidth
- [Exactly once.] + [Exactly once.]
- The measured bandwidth of this relay. + The measured bandwidth of this relay.
- No Zero Bandwidths: - Tor accepts zero bandwidths, but they trigger bugs in older Tor - implementations. Therefore, implementations SHOULD NOT produce zero - bandwidths. Instead, they SHOULD use one as their minimum bandwidth. - If there are zero bandwidths, the parser MAY ignore them. + No Zero Bandwidths: + Tor accepts zero bandwidths, but they trigger bugs in older Tor + implementations. Therefore, implementations SHOULD NOT produce zero + bandwidths. Instead, they SHOULD use one as their minimum bandwidth. + If there are zero bandwidths, the parser MAY ignore them.
- Bandwidth Aggregation: - Multiple measurements can be aggregated using an averaging scheme, - such as a mean, median, or decaying average. + Bandwidth Aggregation: + Multiple measurements can be aggregated using an averaging scheme, + such as a mean, median, or decaying average.
- Bandwidth Scaling: - Torflow scales bandwidths to kilobytes per second. Other - implementations SHOULD use kilobytes per second for their initial - bandwidth scaling. + Bandwidth Scaling: + Torflow scales bandwidths to kilobytes per second. Other + implementations SHOULD use kilobytes per second for their initial + bandwidth scaling.
- If different implementations or configurations are used in votes for - the same network, their measurements MAY need further scaling. See - Appendix B for information about scaling, and one possible scaling - method. + If different implementations or configurations are used in votes for + the same network, their measurements MAY need further scaling. See + Appendix B for information about scaling, and one possible scaling + method.
- MaxAdvertisedBandwidth: - Bandwidth generators MUST limit the relays' measured bandwidth based - on the MaxAdvertisedBadwidth. - A relay's MaxAdvertisedBandwidth limits the bandwidth-avg in its - descriptor. bandwidth-avg is the minimum of MaxAdvertisedBandwidth, - BandwidthRate, RelayBandwidthRate, BandwidthBurst, and - RelayBandwidthBurst. - Therefore, generators MUST limit a relay's measured bandwidth to its - descriptor's bandwidth-avg. This limit needs to be implemented in the - generator, because generators may scale consensus weights before - sending them to Tor. - Generators SHOULD NOT limit measured bandwidths based on descriptors' - bandwidth-observed, because that penalises new relays. + MaxAdvertisedBandwidth: + Bandwidth generators MUST limit the relays' measured bandwidth based + on the MaxAdvertisedBadwidth. + A relay's MaxAdvertisedBandwidth limits the bandwidth-avg in its + descriptor. bandwidth-avg is the minimum of MaxAdvertisedBandwidth, + BandwidthRate, RelayBandwidthRate, BandwidthBurst, and + RelayBandwidthBurst. + Therefore, generators MUST limit a relay's measured bandwidth to its + descriptor's bandwidth-avg. This limit needs to be implemented in the + generator, because generators may scale consensus weights before + sending them to Tor. + Generators SHOULD NOT limit measured bandwidths based on descriptors' + bandwidth-observed, because that penalises new relays.
- sbws limits the relay's measured bandwidth to the bandwidth-avg - advertised. + sbws limits the relay's measured bandwidth to the bandwidth-avg + advertised.
- Torflow partitions relays based on their bandwidth. For unmeasured - relays, Torflow uses the minimum of all descriptor bandwidths, - including bandwidth-avg (MaxAdvertisedBandwidth) and - bandwidth-observed. Then Torflow measures the relays in each partition - against each other, which implicitly limits a relay's measured - bandwidth to the bandwidths of similar relays. + Torflow partitions relays based on their bandwidth. For unmeasured + relays, Torflow uses the minimum of all descriptor bandwidths, + including bandwidth-avg (MaxAdvertisedBandwidth) and + bandwidth-observed. Then Torflow measures the relays in each partition + against each other, which implicitly limits a relay's measured + bandwidth to the bandwidths of similar relays.
- Torflow also generates consensus weights based on the ratio between the - measured bandwidth and the minimum of all descriptor bandwidths (at the - time of the measurement). So when an operator reduces the - MaxAdvertisedBandwidth for a relay, Torflow reduces that relay's - measured bandwidth. + Torflow also generates consensus weights based on the ratio between the + measured bandwidth and the minimum of all descriptor bandwidths (at the + time of the measurement). So when an operator reduces the + MaxAdvertisedBandwidth for a relay, Torflow reduces that relay's + measured bandwidth.
- KeyValue + KeyValue
- [Zero or more times.] + [Zero or more times.]
- Future format versions may include additional KeyValue pairs on a - RelayLine. - Additional KeyValue pairs will be accompanied by a minor version - increment. + Future format versions may include additional KeyValue pairs on a + RelayLine. + Additional KeyValue pairs will be accompanied by a minor version + increment.
- Implementations MAY add additional relay KeyValue pairs as needed. - This specification SHOULD be updated to avoid conflicting meanings - for the same Keywords. + Implementations MAY add additional relay KeyValue pairs as needed. + This specification SHOULD be updated to avoid conflicting meanings + for the same Keywords.
- Parsers MUST NOT rely on the order of these additional KeyValue - pairs. + Parsers MUST NOT rely on the order of these additional KeyValue + pairs.
- Additional KeyValue pairs MUST NOT use any keywords specified in the - header format. - If there are, the parser MAY ignore conflicting keywords. + Additional KeyValue pairs MUST NOT use any keywords specified in the + header format. + If there are, the parser MAY ignore conflicting keywords.
2.4. Implementation details
2.4.1 Writing bandwidth files atomically
-To avoid inconsistent reads, implementations SHOULD write bandwidth files -atomically. If the file is transferred from another host, it SHOULD be -written to a temporary path, then renamed to the V3BandwidthsFile path. + To avoid inconsistent reads, implementations SHOULD write bandwidth files + atomically. If the file is transferred from another host, it SHOULD be + written to a temporary path, then renamed to the V3BandwidthsFile path.
-sbws versions 0.7.0 and later write the bandwidth file to an archival location, -create a temporary symlink to that location, then atomically rename the symlink -to the configured V3BandwidthsFile path. + sbws versions 0.7.0 and later write the bandwidth file to an archival + location, create a temporary symlink to that location, then atomically rename + the symlink + to the configured V3BandwidthsFile path.
-Torflow does not write bandwidth files atomically. + Torflow does not write bandwidth files atomically.
2.4.2. Additional KeyValue pair definitions
-KeyValue pairs in RelayLines that current implementations generate. + KeyValue pairs in RelayLines that current implementations generate.
2.4.2.1. Simple Bandwidth Scanner
-Every RelayLine in sbws version 0.1.0 consists of: + Every RelayLine in sbws version 0.1.0 consists of:
- "node_id=" hexdigest SP + "node_id=" hexdigest SP
- As above. + As above.
- "bw=" Bandwidth SP + "bw=" Bandwidth SP
- As above. + As above.
- "nick=" nickname SP + "nick=" nickname SP
- [Exactly once.] + [Exactly once.]
- The relay nickname. + The relay nickname.
- "rtt=" Int SP + "rtt=" Int SP
- [Exactly once.] + [Exactly once.]
- The Round Trip Time in milliseconds to obtain 1 byte of data. + The Round Trip Time in milliseconds to obtain 1 byte of data.
- "time=" DateTime NL + "time=" DateTime NL
- [Exactly once.] + [Exactly once.]
- The date and time timestamp in ISO 8601 format and UTC time zone - when the last bandwidth was obtained. + The date and time timestamp in ISO 8601 format and UTC time zone + when the last bandwidth was obtained.
- "success=" Int NL + "success=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of times that the bandwidth measurements for this relay were - successful. + The number of times that the bandwidth measurements for this relay were + successful.
- "error_circ=" Int NL + "error_circ=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of times that the bandwidth measurements for this relay - failed because of circuit failures. + The number of times that the bandwidth measurements for this relay + failed because of circuit failures.
- "error_stream=" Int NL + "error_stream=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of times that the bandwidth measurements for this relay - failed because of stream failures. + The number of times that the bandwidth measurements for this relay + failed because of stream failures.
- "error_misc=" Int NL + "error_misc=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The number of times that the bandwidth measurements for this relay - failed because of other reasons. + The number of times that the bandwidth measurements for this relay + failed because of other reasons.
- "bw_mean=" Int NL + "bw_mean=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The measured bandwidth mean for this relay. + The measured bandwidth mean for this relay.
- "bw_median=" Int NL + "bw_median=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The measured bandwidth median for this relay. + The measured bandwidth median for this relay.
- "desc_bw_average=" Int NL + "desc_bw_average=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The descriptor average bandwidth for this relay. + The descriptor average bandwidth for this relay.
- "desc_bw_obs_last=" Int NL + "desc_bw_obs_last=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The last descriptor observed bandwidth for this relay. + The last descriptor observed bandwidth for this relay.
- "desc_bw_obs_mean=" Int NL + "desc_bw_obs_mean=" Int NL
- [Zero or one time.] + [Zero or one time.]
- The descriptor observed bandwidth mean for this relay. + The descriptor observed bandwidth mean for this relay.
2.4.2.2. Torflow
-Torflow RelayLines include node_id and bw, and other KeyValue pairs [2]. + Torflow RelayLines include node_id and bw, and other KeyValue pairs [2].
References:
@@ -550,7 +552,7 @@ The following has not been obtained from any real measurement.
A.1. Generated by Torflow
-This an example version 1.0.0 document: + This an example version 1.0.0 document:
1523911758 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 @@ -589,7 +591,7 @@ 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
-When there are not enough eligible measured relays: + When there are not enough eligible measured relays:
1540496079 version=1.2.0 @@ -610,113 +612,113 @@ B. Scaling bandwidths
B.1. Scaling requirements
-Tor accepts zero bandwidths, but they trigger bugs in older Tor -implementations. Therefore, scaling methods SHOULD perform the -following checks: - * If the total bandwidth is zero, all relays should be given equal + Tor accepts zero bandwidths, but they trigger bugs in older Tor + implementations. Therefore, scaling methods SHOULD perform the + following checks: + * If the total bandwidth is zero, all relays should be given equal bandwidths. - * If the scaled bandwidth is zero, it should be rounded up to one. + * If the scaled bandwidth is zero, it should be rounded up to one.
-Initial experiments indicate that scaling may not be needed for -torflow and sbws, because their measured bandwidths are similar -enough already. + Initial experiments indicate that scaling may not be needed for + torflow and sbws, because their measured bandwidths are similar + enough already.
B.2. A linear scaling method
-If scaling is required, here is a simple linear bandwith scaling -method, which ensures that all bandwidth votes contain approximately -the same total bandwidth: + If scaling is required, here is a simple linear bandwith scaling + method, which ensures that all bandwidth votes contain approximately + the same total bandwidth:
-1. Calculate the relay quota by dividing the total measured bandwidth - in all votes, by the number of relays with measured bandwidth - votes. In the public tor network, this is approximately 7500 as of - April 2018. The quota should be a consensus parameter, so it can be - adjusted for all generators on the network. + 1. Calculate the relay quota by dividing the total measured bandwidth + in all votes, by the number of relays with measured bandwidth + votes. In the public tor network, this is approximately 7500 as of + April 2018. The quota should be a consensus parameter, so it can be + adjusted for all generators on the network.
-2. Calculate a vote quota by multiplying the relay quota by the number - of relays this bandwidth authority has measured - bandwidths for. + 2. Calculate a vote quota by multiplying the relay quota by the number + of relays this bandwidth authority has measured + bandwidths for.
-3. Calculate a scaling factor by dividing the vote quota by the - total unscaled measured bandwidth in this bandwidth - authority's upcoming vote. + 3. Calculate a scaling factor by dividing the vote quota by the + total unscaled measured bandwidth in this bandwidth + authority's upcoming vote.
-4. Multiply each unscaled measured bandwidth by the scaling - factor. + 4. Multiply each unscaled measured bandwidth by the scaling + factor.
-Now, the total scaled bandwidth in the upcoming vote is -approximately equal to the quota. + Now, the total scaled bandwidth in the upcoming vote is + approximately equal to the quota.
B.3. Quota changes
-If all generators are using scaling, the quota can be gradually -reduced or increased as needed. Smaller quotas decrease the size -of uncompressed consensuses, and may decrease the size of -consensus diffs and compressed consensuses. But if the relay -quota is too small, some relays may be over- or under-weighted. + If all generators are using scaling, the quota can be gradually + reduced or increased as needed. Smaller quotas decrease the size + of uncompressed consensuses, and may decrease the size of + consensus diffs and compressed consensuses. But if the relay + quota is too small, some relays may be over- or under-weighted.
B.4. Torflow aggreation
-Torflow implements two methods to compute the bandwidth values from the -(stream) bandwidth measurements: with and without PID control feedback. -The method described here is without PID control (see Torflow -specification, section 2.2). + Torflow implements two methods to compute the bandwidth values from the + (stream) bandwidth measurements: with and without PID control feedback. + The method described here is without PID control (see Torflow + specification, section 2.2).
-In the following sections, the relays' measured bandwidth refer to the -ones that this bandwidth authority has measured for the relays that -would be included in the next bandwidth authority's upcoming vote. + In the following sections, the relays' measured bandwidth refer to the + ones that this bandwidth authority has measured for the relays that + would be included in the next bandwidth authority's upcoming vote.
-1. Calculate the filtered bandwidth for each relay: - - choose the relay's measurements (`bw_j`) that are equal or greater - than the mean of the measurements for this relay - - calculate the mean of those measurements + 1. Calculate the filtered bandwidth for each relay: + - choose the relay's measurements (`bw_j`) that are equal or greater + than the mean of the measurements for this relay + - calculate the mean of those measurements
- In pseudocode: + In pseudocode:
bw_filt_i = mean(max(mean(bw_j), bw_j))
-2. Calculate network averages: - - calculate the filtered average by dividing the sum of all the - relays' filtered bandwidth by the number of relays that have been - measured (`n`), ie, calculate the mean average of the relays' - filtered bandwidth. - - calculate the stream average by dividing the sum of all the - relays' filtered bandwidth by the number of relays that have been - measured (`n`), ie, calculate the mean average or the relays' + 2. Calculate network averages: + - calculate the filtered average by dividing the sum of all the + relays' filtered bandwidth by the number of relays that have been + measured (`n`), ie, calculate the mean average of the relays' + filtered bandwidth. + - calculate the stream average by dividing the sum of all the + relays' filtered bandwidth by the number of relays that have been + measured (`n`), ie, calculate the mean average or the relays' measured bandwidth.
- In pseudocode: + In pseudocode:
- bw_avg_filt_ = bw_filt_i / n - bw_avg_strm = bw_i / n + bw_avg_filt_ = bw_filt_i / n + bw_avg_strm = bw_i / n
-3. Calculate ratios for each relay: - - calculate the filtered ratio by dividing each relay filtered - bandwidth by the filtered average - - calculate the stream ratio by dividing each relay measured - bandwidth by the stream average + 3. Calculate ratios for each relay: + - calculate the filtered ratio by dividing each relay filtered + bandwidth by the filtered average + - calculate the stream ratio by dividing each relay measured + bandwidth by the stream average
- In pseudocode: + In pseudocode:
- r_filt_i = bw_filt_i / bw_avg_filt - r_strm_i = bw_i / bw_avg_strm + r_filt_i = bw_filt_i / bw_avg_filt + r_strm_i = bw_i / bw_avg_strm
-4. Calculate the final ratio for each relay: - The final ratio is the larger between the filtered bandwidth and the - stream bandwidth. + 4. Calculate the final ratio for each relay: + The final ratio is the larger between the filtered bandwidth and the + stream bandwidth.
- In pseudocode: + In pseudocode:
- r_i = max(r_filt_i, r_strm_i) + r_i = max(r_filt_i, r_strm_i)
-5. Calculate the scaled bandwidth for each relay: - The most recent descriptor observed bandwidth (`bw_obs_i`) is - multiplied by the ratio + 5. Calculate the scaled bandwidth for each relay: + The most recent descriptor observed bandwidth (`bw_obs_i`) is + multiplied by the ratio
- In pseudocode: + In pseudocode:
- bw_new_i = r_i * bw_obs_i + bw_new_i = r_i * bw_obs_i
- <<In this way, the resulting network status consensus bandwidth - values are effectively re-weighted proportional to how much faster - the node was as compared to the rest of the network.>> + <<In this way, the resulting network status consensus bandwidth + values are effectively re-weighted proportional to how much faster + the node was as compared to the rest of the network.>>