Opened 6 years ago

Closed 13 months ago

#8494 closed defect (fixed)

Document MaxAdvertisedBandwidth in the bandwidth list spec

Reported by: alphawolf Owned by: juga
Priority: Low Milestone: Tor: 0.3.5.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: tor-spec, consensus, bandwidth, MaxAdvertisedBandwidth tor-relay tor-dirauth needs-insight tor-bwauth
Cc: mikeperry Actual Points:
Parent ID: #25925 Points:
Reviewer: Sponsor:

Description

I've set MaxAdvertisedBandwidth to 100 KB (though RelayBandwidthRate and RelayBandwidthBurst are set to 128 KB and 153 KB, respectively). Accordingly, the relay does not advertise any bandwidth higher than 100 KB. However, the consensus is reporting greater bandwidth:

valid-after 2013-03-17 01:00:00
r PrivateJoker hWF85kNElIsLrCPNTiIkX39mwcg r5DGWEd9ufF4TFXJITuOhw+by6I 2013-03-16 19:18:56 107.197.196.79 443 80
s Fast Named Running Stable V2Dir Valid
v Tor 0.2.4.11-alpha
w Bandwidth=108
p reject 1-65535

The bandwidth line from the descriptor looks like:

bandwidth 102400 156672 155648

My understanding is that clients use the consensus bandwidth measurement to weigh which paths to choose (correct me if I'm wrong).  If this is true, then the consensus should not report bandwidth greater than MaxAdvertisedBandwidth.  Perhaps the consensus should never show bandwidth greater than a relay's chosen RelayBandwidthRate?

Child Tickets

Change History (23)

comment:1 Changed 6 years ago by nickm

Cc: mikeperry added
Milestone: Tor: unspecified

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?

comment:2 Changed 6 years ago by alphawolf

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".

comment:3 Changed 6 years ago by nickm

Keywords: consensus tor-relay added; consesnsus removed

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.

comment:4 Changed 2 years ago by nickm

Keywords: tor-dirauth needs-insight added
Priority: MediumLow
Severity: Normal
Summary: Relay bandwidth in consensus should not exceed MaxAdvertisedBandwidthDoes MaxAdvertisedBandwidth do anything useful and if not, can we deprecate it?

comment:5 Changed 2 years ago by Sebastian

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.

comment:6 Changed 15 months ago by teor

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).

comment:7 Changed 15 months ago by teor

Component: Core Tor/TorCore Tor/Torflow
Milestone: Tor: unspecifiedTor: 0.3.5.x-final
Owner: set to tom
Parent ID: #25960
Version: Tor: 0.2.4.11-alpha

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.

comment:8 Changed 15 months ago by teor

Component: Core Tor/TorflowCore Tor/Tor

comment:9 Changed 13 months ago by juga

Cc: juga added
Keywords: tor-bwauth added

comment:10 Changed 13 months ago by teor

Keywords: tor-spec added

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

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

comment:11 Changed 13 months ago by teor

Parent ID: #25960

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

comment:12 Changed 13 months ago by juga

ACK, will do this weekend

comment:13 Changed 13 months ago by 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
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

comment:14 Changed 13 months ago by juga

Cc: juga removed
Owner: changed from tom to juga
Parent ID: #25925
Status: newassigned

comment:15 in reply to:  13 ; Changed 13 months ago by 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.

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".

Last edited 13 months ago by teor (previous) (diff)

comment:16 in reply to:  15 ; Changed 13 months ago by 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?

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

comment:17 in reply to:  16 ; Changed 13 months ago by teor

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

Last edited 13 months ago by teor (previous) (diff)

comment:18 Changed 13 months ago by teor

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

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

comment:19 in reply to:  17 ; Changed 13 months ago by 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.

[...]

  1. MaxAdvertisedBandwidth

[The text above without 1st sentence]

Does this sounds good?

Please open another ticket for changes to other specs.

i've created #26478

comment:20 in reply to:  19 ; Changed 13 months ago by teor

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.

[...]

  1. 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.

comment:21 in reply to:  20 Changed 13 months ago by juga

Status: assignedneeds_review

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.

comment:22 Changed 13 months ago by teor

Status: needs_reviewmerge_ready

Looks good to me

comment:23 Changed 13 months ago by nickm

Resolution: fixed
Status: merge_readyclosed

Merged!

Note: See TracTickets for help on using tickets.