Skip to content
Snippets Groups Projects
New look: Off

Tor Manual: Split Circuit Timeout options into their own subsection

    • Closed (moved) Issue created by teor @teor

    Let's put the CircuitTimeout options in their own manpage section.

    For context, see: https://trac.torproject.org/projects/tor/ticket/32846#comment:11

    To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information

    Child items 0

    • No child items are currently assigned. Use child items to break down this issue into smaller parts.

    Activity

    • teor changed milestone to %Tor: 0.4.3.x-final

      changed milestone to %Tor: 0.4.3.x-final

    • Trac
      Trac @tracbot ·

      Trac:
      Parent Ticket: #4310 (moved)

    • teor added 043-can component::core tor/tor documentation easy extra-review manpage milestone::Tor: 0.4.3.x-final parent::4310 points::0.5 priority::medium resolution::implemented reviewer::catalyst reviewer::nickm severity::normal status::closed tor-client type::task labels

      added 043-can component::core tor/tor documentation easy extra-review manpage milestone::Tor: 0.4.3.x-final parent::4310 points::0.5 priority::medium resolution::implemented reviewer::catalyst reviewer::nickm severity::normal status::closed tor-client type::task labels

    • Trac
      Trac @tracbot ·

      Added a new section called Timeout Options. See PR - https://github.com/torproject/tor/pull/1702 Currently, there are 7 options in this section.

      Some questions:

      • Is the Timeout Options an appropriate title for this category?

      • Do the following options also belong to the Timeout Options category? MaxCircuitDirtiness MaxClientCircuitsPending CircuitPadding ReducedCircuitPadding NewCircuitPeriod PathsNeededToBuildCircuits

      If yes, I will have to add these too.

      Trac:
      Username: swati

    • Trac
      Trac @tracbot ·

      Trac:
      Username: swati
      Status: new to needs_review

    • Trac
      Trac @tracbot ·

      Trac:
      Username: swati
      Reviewer: N/A to teor, catalyst

    • C
      Taylor Yu @catalyst ·

      Thanks!

      It mostly looks good. I think it's better to have a title like "Circuit timeout options". (I think we don't currently have any timeout options other than circuit timeout options, but we might in the future.)

      I'll try to comment more after the weekend.

      Trac:
      Keywords: documentation tor-client manpage easy 043-can deleted, documentation tor-client manpage easy 043-can extra-review added

    • T
      teor @teor ·
      Author

      Hi, I'm busy with Sponsor 55 right now, can you find someone else to review?

      Trac:
      Reviewer: teor, catalyst to catalyst

    • Trac
      Trac @tracbot ·

      Thanks, Taylor. Regarding your comment about renaming the section to 'Circuit Timeout Options', I see that I have added DormantClientTimeout and DormantTimeoutDisabledByIdleStreams options to this section. Are these two circuit options as well?

      Also, should I add the following circuit options to this section:?

      MaxCircuitDirtiness MaxClientCircuitsPending CircuitPadding ReducedCircuitPadding NewCircuitPeriod PathsNeededToBuildCircuits

      Replying to catalyst:

      Thanks!

      It mostly looks good. I think it's better to have a title like "Circuit timeout options". (I think we don't currently have any timeout options other than circuit timeout options, but we might in the future.)

      I'll try to comment more after the weekend.

      Trac:
      Username: swati

    • Trac
      Trac @tracbot ·

      Taylor, Could you please add any other reviewers?

      Replying to teor:

      Hi, I'm busy with Sponsor 55 right now, can you find someone else to review?

      Trac:
      Username: swati

    • C
      Taylor Yu @catalyst ·

      Replying to swati:

      Thanks, Taylor. Regarding your comment about renaming the section to 'Circuit Timeout Options', I see that I have added DormantClientTimeout and DormantTimeoutDisabledByIdleStreams options to this section. Are these two circuit options as well?

      I see. I think you're right there. They're client options that aren't directly related to circuit timeouts. They might belong in a separate section about Dormant mode?

      Also, should I add the following circuit options to this section:?

      Unfortunately, I think these are a little bit tricky to classify. Maybe we want to expand the section heading to include client circuit behavior overall? (The Nodes options have to do with the details of building a circuit, while many of these operations are at a higher level of abstraction that ignores individual nodes in a circuit.)

      MaxCircuitDirtiness

      I think this is not directly timing related? This is related to reusing a circuit for multiple application streams. I think there is a tradeoff between circuit reuse (for efficiency and decreased latency) and traffic analysis risk.

      MaxClientCircuitsPending

      I'm not quite sure how this one interacts with timing.

      CircuitPadding ReducedCircuitPadding

      I think these aren't directly timing-related. These options are related to a countermeasure that we use against traffic analysis. There is a tradeoff because the countermeasure can increase bandwidth consumption. (I guess in situations of highly constrained bandwidth it could decrease performance in a user-visible way.)

      NewCircuitPeriod PathsNeededToBuildCircuits

      These help tor decide when to build new circuits. PathsNeededToBuildCircuits is a bit more strongly related to the bootstrapping process than the other options here, so I'm not quite sure whether it belongs with the others.

    • C
      Taylor Yu @catalyst ·

      Trac:
      Reviewer: catalyst to catalyst, nickm

    • Trac
      Trac @tracbot ·

      Replying to catalyst:

      Replying to swati:

      Thanks, Taylor. Regarding your comment about renaming the section to 'Circuit Timeout Options', I see that I have added DormantClientTimeout and DormantTimeoutDisabledByIdleStreams options to this section. Are these two circuit options as well?

      I see. I think you're right there. They're client options that aren't directly related to circuit timeouts. They might belong in a separate section about Dormant mode?

      Currently, there are only four Dormant mode options in the manual - DormantCanceledByStartup, DormantOnFirstStartup, DormantClientTimeout and DormantTimeoutDisabledByIdleStreams. Do you think we can have a separate section for dormant mode with just these four options? If yes, I'll put them out from here and create a new section.

      Also, should I add the following circuit options to this section:?

      Unfortunately, I think these are a little bit tricky to classify. Maybe we want to expand the section heading to include client circuit behavior overall? (The Nodes options have to do with the details of building a circuit, while many of these operations are at a higher level of abstraction that ignores individual nodes in a circuit.)

      MaxCircuitDirtiness

      I think this is not directly timing related? This is related to reusing a circuit for multiple application streams. I think there is a tradeoff between circuit reuse (for efficiency and decreased latency) and traffic analysis risk.

      MaxClientCircuitsPending

      I'm not quite sure how this one interacts with timing.

      CircuitPadding ReducedCircuitPadding

      I think these aren't directly timing-related. These options are related to a countermeasure that we use against traffic analysis. There is a tradeoff because the countermeasure can increase bandwidth consumption. (I guess in situations of highly constrained bandwidth it could decrease performance in a user-visible way.)

      NewCircuitPeriod PathsNeededToBuildCircuits

      These help tor decide when to build new circuits. PathsNeededToBuildCircuits is a bit more strongly related to the bootstrapping process than the other options here, so I'm not quite sure whether it belongs with the others.

      Trac:
      Username: swati

    • Nick Mathewson
      Nick Mathewson @nickm ·

      Replying to catalyst:

      Replying to swati:

      Thanks, Taylor. Regarding your comment about renaming the section to 'Circuit Timeout Options', I see that I have added DormantClientTimeout and DormantTimeoutDisabledByIdleStreams options to this section. Are these two circuit options as well?

      I see. I think you're right there. They're client options that aren't directly related to circuit timeouts. They might belong in a separate section about Dormant mode?

      [...]

      For what it's worth, I agree with catalyst in their assessment of the options discussed in the comment above.

    • Nick Mathewson
      Nick Mathewson @nickm ·

      Replying to swati:

      Replying to catalyst:

      Replying to swati:

      Thanks, Taylor. Regarding your comment about renaming the section to 'Circuit Timeout Options', I see that I have added DormantClientTimeout and DormantTimeoutDisabledByIdleStreams options to this section. Are these two circuit options as well?

      I see. I think you're right there. They're client options that aren't directly related to circuit timeouts. They might belong in a separate section about Dormant mode?

      Currently, there are only four Dormant mode options in the manual - DormantCanceledByStartup, DormantOnFirstStartup, DormantClientTimeout and DormantTimeoutDisabledByIdleStreams. Do you think we can have a separate section for dormant mode with just these four options? If yes, I'll put them out from here and create a new section.

      I think that's a fine idea.

    • Trac
      Trac @tracbot ·

      Hey nickm and catalyst,

      • I added a new section called Dormant Mode Options and moved the four options under this section. Does anyone want to suggest a better introductory sentence for this section?
      • Also, I renamed the Timeout Options section to Circuit Timeout Options, as suggested by catalyst. I haven't moved the other options that aren't directly related to timeout under this section. Leaving them where they are for now. Is that okay?
      • Can we consider this ticket resolved? If yes, can we merge the PR so that I can continue working on the rest of the manual?

      Thank you, Swati

      Trac:
      Username: swati

    • Nick Mathewson
      Nick Mathewson @nickm ·

      This looks good to me; I say we should merge if catalyst is okay with it.

    • C
      Taylor Yu @catalyst ·

      Replying to swati:

      Thanks for the changes!

      • I added a new section called Dormant Mode Options and moved the four options under this section. Does anyone want to suggest a better introductory sentence for this section?

      Dormant mode is a state that tor can enter and leave, and the options in this section modify that behavior. Maybe this?

      "Tor can enter a dormant mode to conserve power and network bandwidth. The following options control when tor enters and leaves dormant mode."

      • Also, I renamed the Timeout Options section to Circuit Timeout Options, as suggested by catalyst. I haven't moved the other options that aren't directly related to timeout under this section. Leaving them where they are for now. Is that okay?

      I think that's fine. I couldn't come up with a concise heading for an expanded section that would contain the other options you were considering. I would suggest rewording the introductory paragraph to something like this?

      "The following options are useful for configuring timeouts related to building Tor circuits and using them."

      • Can we consider this ticket resolved? If yes, can we merge the PR so that I can continue working on the rest of the manual?

      I think we're mostly there. There are a couple of minor wording changes I suggested above for the introductory text of the new sections. If you agree, please go ahead and make those changes.

    • Trac
      Trac @tracbot ·

      Replying to catalyst:

      Thanks for the changes!

      • I added a new section called Dormant Mode Options and moved the four options under this section. Does anyone want to suggest a better introductory sentence for this section?

      Dormant mode is a state that tor can enter and leave, and the options in this section modify that behavior. Maybe this?

      "Tor can enter a dormant mode to conserve power and network bandwidth. The following options control when tor enters and leaves dormant mode."

      • Also, I renamed the Timeout Options section to Circuit Timeout Options, as suggested by catalyst. I haven't moved the other options that aren't directly related to timeout under this section. Leaving them where they are for now. Is that okay?

      I think that's fine. I couldn't come up with a concise heading for an expanded section that would contain the other options you were considering. I would suggest rewording the introductory paragraph to something like this?

      "The following options are useful for configuring timeouts related to building Tor circuits and using them."

      • Can we consider this ticket resolved? If yes, can we merge the PR so that I can continue working on the rest of the manual?

      I think we're mostly there. There are a couple of minor wording changes I suggested above for the introductory text of the new sections. If you agree, please go ahead and make those changes.

      Reworded your suggestion a bit and updated the introductory text in both the sections.

      Trac:
      Username: swati

    • C
      Taylor Yu @catalyst ·

      Replying to swati:

      Reworded your suggestion a bit and updated the introductory text in both the sections. Thanks! It looks good. There needs to be a changes file, but I can write one and push it to your branch if that's ok.

    • C
      Taylor Yu @catalyst ·

      Note to merger: please merge https://github.com/torproject/tor/pull/1711 instead; it adds a changes file. Thanks!

      Swati, I think that should auto-close your pull request if it's merged without additional changes or rebasing.

      Trac:
      Status: needs_review to merge_ready

    • Nick Mathewson
      Nick Mathewson @nickm ·

      Merged!

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

    • Trac closed

      closed

    • Trac changed time estimate to 4h

      changed time estimate to 4h

    • Taylor Yu mentioned in issue #32929 (moved)

      mentioned in issue #32929 (moved)

    • Trac moved to tpo/core/tor#32928 (closed)

      moved to tpo/core/tor#32928 (closed)

    Please register or sign in to reply