Opened 7 weeks ago

Closed 6 weeks ago

#33188 closed task (implemented)

Tor Manual: Alphabetize Server and Directory Server Options

Reported by: swati Owned by:
Priority: Medium Milestone:
Component: Core Tor/Tor Version:
Severity: Normal Keywords: documentation tor-client manpage easy 043-can
Cc: catalyst, swati Actual Points:
Parent ID: #4310 Points:
Reviewer: catalyst Sponsor:

Description

Alphabetize options in the Server Options and Directory Server Options

Child Tickets

Change History (13)

comment:1 Changed 7 weeks ago by swati

Hi catalyst,

Created a Pull Request - https://github.com/torproject/tor/pull/1715 for the following changes:

  • Alphabetized the Server and Directory Server Options
  • Created a new section titled Statistics Options. Pulled out all the stats-related and extra-info related options, and put them into this new section.

Should I pull out the DownloadExtraInfo option (that is presently under the Client Options section) and move it under Statistics Options?

comment:2 Changed 7 weeks ago by swati

Status: newneeds_review

comment:3 Changed 7 weeks ago by swati

Reviewer: catalyst

Please feel free to add more reviewers.

comment:4 in reply to:  1 ; Changed 7 weeks ago by catalyst

Replying to swati:

Created a Pull Request - https://github.com/torproject/tor/pull/1715 for the following changes:

  • Alphabetized the Server and Directory Server Options

Thanks! It looks like MaxOnionQueueDelay is out of order, but the rest of Server and Stats options are in order or correctly commented. I'll check the Directory Server options in another comment.

  • Created a new section titled Statistics Options. Pulled out all the stats-related and extra-info related options, and put them into this new section.

Looks good! I would suggest a few minor changes to the introductory text. Change "following options describe" to "following options affect". Change "that Tor collects and writes" to "that Tor relays collect and publish". What do you think?

Should I pull out the DownloadExtraInfo option (that is presently under the Client Options section) and move it under Statistics Options?

I think this still belongs in the Client Options section, because it doesn't affect how relays report their statistics.

Also, I think RephistTrackTime might belong in the stats section, because it changes the length of the period that relays use to report their bandwidth stats. (I'm still researching this. Anyone else have ideas?)

comment:5 in reply to:  4 Changed 7 weeks ago by catalyst

Replying to catalyst:

I'll check the Directory Server options in another comment.

Looks like I got my script for checking the Directory Server options wrong, and it was capturing more than I expected. The Directory Server options look like they're sorted correctly.

comment:6 in reply to:  4 ; Changed 7 weeks ago by nickm

Replying to catalyst:

Replying to swati:

Created a Pull Request - https://github.com/torproject/tor/pull/1715 for the following changes:

  • Alphabetized the Server and Directory Server Options

Thanks! It looks like MaxOnionQueueDelay is out of order, but the rest of Server and Stats options are in order or correctly commented. I'll check the Directory Server options in another comment.

  • Created a new section titled Statistics Options. Pulled out all the stats-related and extra-info related options, and put them into this new section.

Looks good! I would suggest a few minor changes to the introductory text. Change "following options describe" to "following options affect". Change "that Tor collects and writes" to "that Tor relays collect and publish". What do you think?

Should I pull out the DownloadExtraInfo option (that is presently under the Client Options section) and move it under Statistics Options?

I think this still belongs in the Client Options section, because it doesn't affect how relays report their statistics.

Also, I think RephistTrackTime might belong in the stats section, because it changes the length of the period that relays use to report their bandwidth stats. (I'm still researching this. Anyone else have ideas?)

Everything with "Rephist" in the name should go under statistics.

comment:7 Changed 7 weeks ago by catalyst

Status: needs_reviewneeds_revision

Looks fairly good so far. It could use a few minor changes:

comment:8 in reply to:  6 ; Changed 7 weeks ago by teor

Replying to nickm:

Replying to catalyst:

Replying to swati:

Created a Pull Request - https://github.com/torproject/tor/pull/1715 for the following changes:

  • Created a new section titled Statistics Options. Pulled out all the stats-related and extra-info related options, and put them into this new section.

Looks good! I would suggest a few minor changes to the introductory text. Change "following options describe" to "following options affect". Change "that Tor collects and writes" to "that Tor relays collect and publish". What do you think?

Should I pull out the DownloadExtraInfo option (that is presently under the Client Options section) and move it under Statistics Options?

I think this still belongs in the Client Options section, because it doesn't affect how relays report their statistics.

I agree, the DownloadExtraInfo option works on clients and relays, so it should not be in a relay-only section.

Also, I think RephistTrackTime might belong in the stats section, because it changes the length of the period that relays use to report their bandwidth stats. (I'm still researching this. Anyone else have ideas?)

Everything with "Rephist" in the name should go under statistics.

RephistTrackTime is used to clean router reputation history. This history is used by clients, relays, and authorities (in different ways). See:
https://gitweb.torproject.org/tor.git/tree/src/core/mainloop/mainloop.c#n1412
https://gitweb.torproject.org/tor.git/tree/src/core/mainloop/mainloop.c#n2008

Authorities use it in their votes, clients and relays use it to check whether another relay might be up.

So I think RephistTrackTime belongs in some sort of "common options" section. (Or in client options, if there isn't a common options section.)

The bandwidth stats interval is a fixed constant, as are all stats intervals. We don't let people configure them, it would make metrics code much more complex :-)

comment:9 in reply to:  8 Changed 6 weeks ago by catalyst

Hi swati, I think I agree with teor after thinking about it some more. Please leave RephistTrackTime alone, or move it to General Options. Its content might need improvement (to make it clear that all kinds of entities use it), but we can do that separately.

Replying to teor:

RephistTrackTime is used to clean router reputation history. This history is used by clients, relays, and authorities (in different ways). See:
https://gitweb.torproject.org/tor.git/tree/src/core/mainloop/mainloop.c#n1412
https://gitweb.torproject.org/tor.git/tree/src/core/mainloop/mainloop.c#n2008

Authorities use it in their votes, clients and relays use it to check whether another relay might be up.

So I think RephistTrackTime belongs in some sort of "common options" section. (Or in client options, if there isn't a common options section.)

comment:10 in reply to:  7 Changed 6 weeks ago by swati

Replying to catalyst:

Looks fairly good so far. It could use a few minor changes:

Addressed all these suggested updates. According to teor and catalyst, moved RephistTrackTime to the General Options category.

Last edited 6 weeks ago by swati (previous) (diff)

comment:11 Changed 6 weeks ago by swati

Hi catalyst, could you please add a changes file to this ticket and merge it?

Last edited 6 weeks ago by swati (previous) (diff)

comment:12 in reply to:  11 Changed 6 weeks ago by catalyst

Status: needs_revisionmerge_ready

Replying to swati:

Hi catalyst, could you please add a changes file to this ticket and merge it?

Thanks! Looks good to me. I created a changes file.

Merge instructions: pull request including the changes file is at

https://github.com/torproject/tor/pull/1728

please merge that one.

comment:13 Changed 6 weeks ago by nickm

Resolution: implemented
Status: merge_readyclosed

Merged to maint-0.4.3 and forward!

Note: See TracTickets for help on using tickets.