Document MaxAdvertisedBandwidth in the bandwidth list spec

changed milestone to %Tor: 0.3.5.x-final in legacy/trac

I think this is an expected outcome of the bandwidth weighting procedure. It's not reporting how much bandwidth you have; rather it's reporting how much bandwidth you seem to have in comparison with other nodes reporting about 100K of bandwidth. I'm cc'ing mike on this in case he has more to say here, or in case I'm wrong. Mike?

Trac:
Milestone: N/A to Tor: unspecified
Cc: N/A to mikeperry

That could be... but then is there a point to having MaxAdvertisedBandwidth? If I dropped my MaxAdvertisedBandwidth to 20KB, but left RelayBandwidthRate at 128 KB, wouldn't the directory authorities decide that I provide waaay more bandwidth than others reporting 20 KB, causing more circuits to choose my relay and negating the purpose of setting this variable? This bandwidth weighting stuff is confusing :-)

Perhaps I should explain what I'm trying to accomplish, and what I've observed, and we can go from there...

I've noticed that both the traffic I receive and the "bandwidth" in the consensus are rather volatile. For example, when my consensus bandwidth is around my actual bandwidth, I receive lots of traffic... to the point of consistently saturating the RelayBandwidthRate I've set, with frequent spikes up to RelayBandwidthBurst. This tends to be followed by a sharp decrease in my bandwidth as reported in the consensus... which shortly after leads to a dramatic drop in traffic. Then the consensus increases again and we repeat this cycle. I'm trying level out this cycle.

My theory was that if I reported less bandwidth than I actually had (plus had some "reserve" via RelayBandwidthBurst), then there would usually be enough bandwidth available when the "bandwidth scanners" came knocking that they would say "Yep, he's got as much bandwidth as he claims he has". This would, in theory, keep my consensus bandwidth level, and in theory, prevent the surge/drought cycle of traffic. It hasn't actually worked out that way :-) As of right now, the consensus bandwidth for my relay has dropped to "52" (down from "108" when this bug report was created), and my traffic is now but a trickle.

So I guess... does MaxAdvertisedBandwidth actually do anything (or at least a predictable anything)... and if not, perhaps this bug report should be re-named "Deprecate MaxAdvertisedBandwidth".

Trac:
Username: alphawolf

These are good questions, but most of them aren't ones that this bugtracker is well-set-up to answer. For advice on achieving what you want to do, I'd suggest asking on the tor-relays mailing list, where a lot of other relay operators with practical experience hang out. Over here on trac, it's pretty much only Tor developers who spend all our nose in the C code.

I'm going to keep this ticket open, though, since the question of "Does MaxAdvertisedBandwidth do anything useful and if not, can we deprecate it?" is the kind of thing that we should try to do something about on the bugtracker.

Trac:
Keywords: consesnsus, MaxAdvertisedBandwidth deleted, consensus, MaxAdvertisedBandwidth tor-relay added

Trac:
Reviewer: N/A to N/A
Severity: N/A to Normal
Sponsor: N/A to N/A
Keywords: MaxAdvertisedBandwidth tor-relay deleted, MaxAdvertisedBandwidth tor-relay tor-dirauth needs-insight added
Summary: Relay bandwidth in consensus should not exceed MaxAdvertisedBandwidth to Does MaxAdvertisedBandwidth do anything useful and if not, can we deprecate it?
Priority: Medium to Low

This option is used on the bwauth measurement relays and dirauths, which have huge bandwidthrates but low advertised bandwidth. They get measured well, but only according to their self-selected bw tier which is enough to keep their utilization low.

Relays use MaxAdvertisedBandwidth to limit bandwidthrate and bandwidthburst in their descriptors.

But authorities do not limit consensus weight by bandwidthrate. And they shouldn't, because the consensus weight is not directly comparable with the bandwidth rate.

Instead, bandwidth scanners should calculate weights based on bandwidthrate. Torflow sort-of does this using partitions (see above).

This is not a tor bug, it is a Torflow bug.

This is now sbws ticket https://github.com/pastly/simple-bw-scanner/issues/155

We will deal with this issue in the bandwidth spec, then we can close it.

Trac:
Milestone: Tor: unspecified to Tor: 0.3.5.x-final
Component: Core Tor/Tor to Core Tor/Torflow
Owner: N/A to tom
Parent: N/A to legacy/trac#25960 (moved)
Version: Tor: 0.2.4.11-alpha to N/A

Trac:
Component: Core Tor/Torflow to Core Tor/Tor

Trac:
Cc: mikeperry to mikeperry, juga
Keywords: MaxAdvertisedBandwidth tor-relay tor-dirauth needs-insight deleted, MaxAdvertisedBandwidth tor-relay tor-dirauth needs-insight tor-bwauth added

The sbws ticket is fixed, and we won't fix torflow.

Now we need to update the bandwidth file spec to mention MaxAdvertisedBandwidth.

Trac:
Keywords: N/A deleted, tor-spec added

We still need to document MaxAdvertisedBandwidth in the bandwidth file spec.

Trac:
Parent: legacy/trac#25960 (moved) to N/A

ACK, will do this weekend

Bandwidth terms are different in dir-spec.txt and the code. If i'm not mistaken, what is called bandwidthrate [0] in the code when creating the descriptor, is called bandwidth-avg in dir-spec.txt [1]. And it is calculated as the min(BandwidthRate, MaxAdvertisedBandwidth, RelayBandwidthRate) [2]. If this is correct, the paragraph to add in bandwidth-file-spec.txt could be:

sbws limits the relay's measured bandwidth to the bandwidth-avg advertised
in the relay's descriptor, which is the minimum between BandwidthRate,
MaxAdvertisedBandwidth and RelayBandwidthRate in the relay's configuration.

Though probably the last sentence not needed. If Torflow is using also bandwidth-avg, then it could also be added in bandwidth-file-spec.txt:

Torflow does not need to limit the relay's measured bandwidth since it 
partions relays to be measured by bandwidth-avg

Is this correct?.

[0] https://gitweb.torproject.org/tor.git/tree/src/or/router.c#n2370 [1] https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt#n427 [2] https://gitweb.torproject.org/tor.git/tree/src/or/config.c#n1693

Trac:
Status: new to assigned
Cc: mikeperry, juga to mikeperry
Owner: tom to juga
Parent: N/A to legacy/trac#25925 (moved)

This spec tells us what a bandwidth generator needs to do to be compatible with the Tor network. Sometimes it is useful to give examples of how sbws or torflow implements a feature. But first we need to say what any generator must do. Then we can give examples.

So let's start with a sentence like this:

If a relay sets MaxAdvertisedBandwidth, generators MUST give it a similar weight to relays with that bandwidth capacity.

Replying to juga:

Bandwidth terms are different in dir-spec.txt and the code. If i'm not mistaken, what is called bandwidthrate [0] in the code when creating the descriptor, is called bandwidth-avg in dir-spec.txt [1]. And it is calculated as the min(BandwidthRate, MaxAdvertisedBandwidth, RelayBandwidthRate) [2]. If this is correct, the paragraph to add in bandwidth-file-spec.txt could be:
sbws limits the relay's measured bandwidth to the bandwidth-avg advertised

Please say "Bandwidth generators MUST limit the relay's weight based on", not "sbws limits the relay's measured bandwidth to".

in the relay's descriptor, which is the minimum between BandwidthRate,
MaxAdvertisedBandwidth and RelayBandwidthRate in the relay's configuration.

Though probably the last sentence not needed.

I think we need the last sentence, because we need to explain why bandwidth generators need to implement MaxAdvertisedBandwidth.

Let's also say:

Relays limit their bandwidth when BandwdithRate or RelayBandwidthRate are set. These options reduce a relay's bandwidth capacity. But MaxAdvertisedBandwidth doesn't change the relay's bandwidth capacity. Instead, it asks the bandwidth generator to limit the weight of the relay as if the relay's measured bandwidth was min(measured bandwidth, MaxAdvertisedBandwidth).

Generators SHOULD NOT limit weights based on bandwidth-observed, because that penalises new relays.

Then we can give an example of what sbws does:

sbws measures relay bandwidths, then caps the measured bandwidth using bandwidth-avg (MaxAdvertisedBandwidth).

If Torflow is using also bandwidth-avg, then it could also be added in bandwidth-file-spec.txt:
Torflow does not need to limit the relay's measured bandwidth since it 
partions relays to be measured by bandwidth-avg
Is this correct?.

No, Torflow partitions based on:

bandwidth-consensus, if available, or
min(bandwidth-avg, bandwidth-burst, bandwidth-observed), or
1, if either bandwidth is zero.

https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n376 https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n459

Torflow also calculates weights based on the descriptor bandwidth to measured bandwidth ratio.

So let's say:

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.

[0] https://gitweb.torproject.org/tor.git/tree/src/or/router.c#n2370 [1] https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt#n427 [2] https://gitweb.torproject.org/tor.git/tree/src/or/config.c#n1693

Once we add these paragraphs, the bandwidth section will be really long.

Let's split it up into subsections:

No Zero Bandwidths
Bandwidth Aggregation
Bandwidth Scaling
MaxAdvertisedBandwidth

Edit: consistently use "bandwidth capacity" and "measured bandwidth".

Replying to teor:

This spec tells us what a bandwidth generator needs to do to be compatible with the Tor network. Sometimes it is useful to give examples of how sbws or torflow implements a feature. But first we need to say what any generator must do. Then we can give examples.

ACK

So let's start with a sentence like this:
If a relay sets MaxAdvertisedBandwidth, generators MUST give it a similar weight to relays with that bandwidth capacity.
Replying to juga:

Bandwidth terms are different in dir-spec.txt and the code. If i'm not mistaken, what is called bandwidthrate [0] in the code when creating the descriptor, is called bandwidth-avg in dir-spec.txt [1]. And it is calculated as the min(BandwidthRate, MaxAdvertisedBandwidth, RelayBandwidthRate) [2].

Is this correct or i'm mistaken?

If this is correct, the paragraph to add in bandwidth-file-spec.txt could be:
sbws limits the relay's measured bandwidth to the bandwidth-avg advertised
Please say "Bandwidth generators MUST limit the relay's weight based on", not "sbws limits the relay's measured bandwidth to".
in the relay's descriptor, which is the minimum between BandwidthRate,
MaxAdvertisedBandwidth and RelayBandwidthRate in the relay's configuration.
Though probably the last sentence not needed.
I think we need the last sentence, because we need to explain why bandwidth generators need to implement MaxAdvertisedBandwidth.

Let's also say:
Relays limit their bandwidth when BandwdithRate or RelayBandwidthRate are set. These options reduce a relay's bandwidth capacity. But MaxAdvertisedBandwidth doesn't change the relay's bandwidth capacity. Instead, it asks the bandwidth generator to limit the weight of the relay as if the relay's measured bandwidth was min(measured bandwidth, MaxAdvertisedBandwidth).
Generators SHOULD NOT limit weights based on bandwidth-observed, because that penalises new relays.

In all your suggestions, i would not use the word weight to do not confuse it with the weight generated in the consensus. I also would not use the word capacity to do not confuse it with the bandwidth-observed in the descriptors that it's called bandwidthcapacity in the code and comes from relays' self-tests.

Then we can give an example of what sbws does:

sbws measures relay bandwidths, then caps the measured bandwidth using bandwidth-avg (MaxAdvertisedBandwidth).

as mentioned above, isn't bandwidth-avg = min(MaxAdvertisedBandwidth, MaxAdvertisedBandwidth, RelayBandwidthRate)?

If Torflow is using also bandwidth-avg, then it could also be added in bandwidth-file-spec.txt:
Torflow does not need to limit the relay's measured bandwidth since it 
partions relays to be measured by bandwidth-avg
Is this correct?.
No, Torflow partitions based on:

bandwidth-consensus, if available, or

min(bandwidth-avg, bandwidth-burst, bandwidth-observed), or

1, if either bandwidth is zero.

https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n376 https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n459

Torflow also calculates weights based on the descriptor bandwidth to measured bandwidth ratio.

So let's say:
Torflow partitions relays based on their bandwidth. For unmeasured relays, Torflow uses the minimum of all descriptor bandwidths, including bandwidth-avg (MaxAdvertisedBandwidth) 

as mentioned above, isn't bandwidth-avg = min(MaxAdvertisedBandwidth, MaxAdvertisedBandwidth, RelayBandwidthRate)?

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.

So, sumarizing your 4 sentences suggestions with my comments, plus what you clarify about Torflow:

Bandwidth generators MUST limit the relays' measured bandwidth based on the descriptors' bandwidth-avg.
Descriptors' bandwidth-avg is the minimum between BandwidthRate, MaxAdvertisedBandwidth and RelayBandwidthRate in the relays' configuration, when these options are set.
Generators SHOULD NOT limit measured bandwidths based on descriptors' bandwidth-observed, because that penalises new relays.
When generators does not limit the relays' measured bandwidth on the descriptors' bandwidth-avg, they MUST give a similar measured bandwidth to the consensus bandwidth or the minimum between the descriptor's bandwidth-avg, bandwidth-burst or bandwidth-observed.

Though i'm still not sure this is correct. I could just copy what you propose, but not sure about capacity and weight terms, as commented aboved.

As a different issue to solve at some point in the future, i think we should unify terms for bandwidth in Tor code and dir-spec.txt to make it less confusing. It'd be also helpful to add formulae or more detailed descriptions on how the different bandwidth terms are generated in dir-spec.txt

Replying to juga:

Replying to teor:

This spec tells us what a bandwidth generator needs to do to be compatible with the Tor network. Sometimes it is useful to give examples of how sbws or torflow implements a feature. But first we need to say what any generator must do. Then we can give examples.

ACK
So let's start with a sentence like this:
If a relay sets MaxAdvertisedBandwidth, generators MUST give it a similar weight to relays with that bandwidth capacity.
Replying to juga:

Bandwidth terms are different in dir-spec.txt and the code. If i'm not mistaken, what is called bandwidthrate [0] in the code when creating the descriptor, is called bandwidth-avg in dir-spec.txt [1]. And it is calculated as the min(BandwidthRate, MaxAdvertisedBandwidth, RelayBandwidthRate) [2].
Is this correct or i'm mistaken?

bandwidth-avg is min(MaxAdvertisedBandwidth, BandwidthRate, RelayBandwidthRate, BandwidthBurst, RelayBandwidthBurst)

If this is correct, the paragraph to add in bandwidth-file-spec.txt could be:
sbws limits the relay's measured bandwidth to the bandwidth-avg advertised
Please say "Bandwidth generators MUST limit the relay's weight based on", not "sbws limits the relay's measured bandwidth to".
in the relay's descriptor, which is the minimum between BandwidthRate,
MaxAdvertisedBandwidth and RelayBandwidthRate in the relay's configuration.
Though probably the last sentence not needed.
I think we need the last sentence, because we need to explain why bandwidth generators need to implement MaxAdvertisedBandwidth.

Let's also say:
Relays limit their bandwidth when BandwdithRate or RelayBandwidthRate are set. These options reduce a relay's bandwidth capacity. But MaxAdvertisedBandwidth doesn't change the relay's bandwidth capacity. Instead, it asks the bandwidth generator to limit the weight of the relay as if the relay's measured bandwidth was min(measured bandwidth, MaxAdvertisedBandwidth).
Generators SHOULD NOT limit weights based on bandwidth-observed, because that penalises new relays.
In all your suggestions, i would not use the word weight to do not confuse it with the weight generated in the consensus.

When I say "weight", I mean "the weight generated in the consensus", rather than "the bandwidth measured for the relay".

Some generators don't measure relay bandwidth. For example, peerflow aggregates a relay's observed bandwidths from other relays. That's why I said "consensus weight".

But we are not making that distinction in the spec, so we can just say "measured bandwidth".

I also would not use the word capacity to do not confuse it with the bandwidth-observed in the descriptors that it's called bandwidthcapacity in the code and comes from relays' self-tests.

When I said "capacity", I mean "the total amount of bandwidth the relay can handle". I didn't want to say "measured bandwidth", because that's "the extra amount of bandwidth the relay can handle". But we're not making that distinction in the spec either, so we can just say "measured bandwidth" here as well.

Then we can give an example of what sbws does:
sbws measures relay bandwidths, then caps the measured bandwidth using bandwidth-avg (MaxAdvertisedBandwidth).
as mentioned above, isn't bandwidth-avg = min(MaxAdvertisedBandwidth, MaxAdvertisedBandwidth, RelayBandwidthRate)?

No, see above.

If Torflow is using also bandwidth-avg, then it could also be added in bandwidth-file-spec.txt:
Torflow does not need to limit the relay's measured bandwidth since it 
partions relays to be measured by bandwidth-avg
Is this correct?.
No, Torflow partitions based on:

bandwidth-consensus, if available, or

min(bandwidth-avg, bandwidth-burst, bandwidth-observed), or

1, if either bandwidth is zero.

https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n376 https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py#n459

Torflow also calculates weights based on the descriptor bandwidth to measured bandwidth ratio.

So let's say:
Torflow partitions relays based on their bandwidth. For unmeasured relays, Torflow uses the minimum of all descriptor bandwidths, including bandwidth-avg (MaxAdvertisedBandwidth) 
as mentioned above, isn't bandwidth-avg = min(MaxAdvertisedBandwidth, MaxAdvertisedBandwidth, RelayBandwidthRate)?

See above.

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.
So, sumarizing your 4 sentences suggestions with my comments, plus what you clarify about Torflow:

Remember, the spec says what a bandwidth generator needs to do. For complicated tasks, we also say why and how.

Because MaxAdvertisedBadwidth is complicated, I don't want to leave these details out.

Bandwidth generators MUST limit the relays' measured bandwidth based on the descriptors' bandwidth-avg.

I want to say "the relay's MaxAdvertisedBandwidth" in the first sentence, because I want to say why we need to take these extra steps to limit the consensus weight. Then I want to give the details of how MaxAdvertisedBandwidth works in descriptors right now. If we say "bandwidth-avg", we lose the connection between generator bandwidth limits and MaxAdvertisedBandwidth.

Then I want to explain why MaxAdvertisedBandwidth needs to be implemented on bandwidth generators, rather than in Tor itself.

Descriptors' bandwidth-avg is the minimum between BandwidthRate, MaxAdvertisedBandwidth and RelayBandwidthRate in the relays' configuration, when these options are set.

I think we should rewrite this sentence to say:

A relay's MaxAdvertisedBandwidth limits the bandwidth-avg in its descriptor. bandwidth-avg is the minimum of MaxAdvertisedBandwidth, BandwidthRate, RelayBandwidthRate, BandwidthBurst, and RelayBandwidthBurst.

Generators SHOULD NOT limit measured bandwidths based on descriptors' bandwidth-observed, because that penalises new relays.

I agree.

When generators does not limit the relays' measured bandwidth on the descriptors' bandwidth-avg, they MUST give a similar measured bandwidth to the consensus bandwidth or the minimum between the descriptor's bandwidth-avg, bandwidth-burst or bandwidth-observed.

This sentence allows the Torflow behaviour, which is buggy, because it penalises new relays. And it conflicts with the "SHOULD NOT" in the sentence before. if you delete this sentence, the spec will be less confusing.

Edit: Or we could rewrite it as:

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.

You can give the sbws and Torflow implementations as examples if you want.

Though i'm still not sure this is correct. I could just copy what you propose, but not sure about capacity and weight terms, as commented aboved.

You're right, we're not being that specific.

As a different issue to solve at some point in the future, i think we should unify terms for bandwidth in Tor code and dir-spec.txt to make it less confusing. It'd be also helpful to add formulae or more detailed descriptions on how the different bandwidth terms are generated in dir-spec.txt

Please open another ticket for changes to other specs.

What do you think about these subsections?

No Zero Bandwidths
Bandwidth Aggregation
Bandwidth Scaling
MaxAdvertisedBandwidth

Edit: typos

(Changing the ticket name to describe what we're doing in the ticket)

Trac:
Summary: Does MaxAdvertisedBandwidth do anything useful and if not, can we deprecate it? to Document MaxAdvertisedBandwidth in the bandwidth list spec

Collecting all commented lines and including the examples, we would have:

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.

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.

What do you think about these subsections?
No Zero Bandwidths
Bandwidth Aggregation
Bandwidth Scaling
MaxAdvertisedBandwidth

Sounds good, just not sure how you have in mind to include them. A possibility would be:

"bw=" Bandwidth

[Exactly once.]

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.

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.

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. See Appendix C for more information.

[...]

C. MaxAdvertisedBandwidth

[The text above without 1st sentence]

Does this sounds good?

Please open another ticket for changes to other specs.

i've created legacy/trac#26478 (moved)

Replying to juga:

Collecting all commented lines and including the examples, we would have:

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.

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.

What do you think about these subsections?
No Zero Bandwidths
Bandwidth Aggregation
Bandwidth Scaling
MaxAdvertisedBandwidth

Sounds good, just not sure how you have in mind to include them. A possibility would be:

"bw=" Bandwidth

[Exactly once.]

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.

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.

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. See Appendix C for more information.

[...]

C. MaxAdvertisedBandwidth

[The text above without 1st sentence]

Does this sounds good?

The sections look good.

But I'm not sure about the appendix. Appendixes are used for extra information. We put important MUSTs and SHOULD NOTs in the main text, so people don't miss them.

We could put the explanation of bandwidth-avg in an apprendix, but it's only one sentence.

If you want to make the MaxAdvertisedBandwidth section shorter, you can put the sbws and torflow examples in sections 2.4.1 and 2.4.2.

Replying to teor:

But I'm not sure about the appendix. Appendixes are used for extra information. We put important MUSTs and SHOULD NOTs in the main text, so people don't miss them. makes sense, then no appendix We could put the explanation of bandwidth-avg in an apprendix, but it's only one sentence yeah, no worth If you want to make the MaxAdvertisedBandwidth section shorter, you can put the sbws and torflow examples in sections 2.4.1 and 2.4.2. i would then leave the examples in the MaxAdvertisedBandwidth section, because they are specific about MaxAdvertisedBandwidth.

I've created the branch ticket8494 in my repo.

Trac:
Status: assigned to needs_review

Looks good to me

Trac:
Status: needs_review to merge_ready

Merged!

Trac:
Resolution: N/A to fixed
Status: merge_ready to closed

closed

mentioned in issue legacy/trac#25960 (moved)

moved from legacy/trac#8494 (moved)

added Bug label and removed 1 deleted label

added Authority BwAuth Needs Insight Relay Specifications labels and removed 1 deleted label

Document MaxAdvertisedBandwidth in the bandwidth list spec

Child items 0

Activity